@shipfox/api-agent-access-dto 21.0.0 → 21.2.0

package/src/schemas/workflow-execution-events.test.ts

@@ -0,0 +1,126 @@
+import {
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT,
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX,
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES,
+  getExecutionTriggerEventInputJsonSchema,
+  getExecutionTriggerEventInputSchema,
+  getExecutionTriggerEventResultJsonSchema,
+  getExecutionTriggerEventResultSchema,
+  listExecutionTriggerEventsInputSchema,
+  listExecutionTriggerEventsResultJsonSchema,
+  listExecutionTriggerEventsResultSchema,
+} from './workflow-execution-events.js';
+
+const jobId = '00000000-0000-4000-8000-000000000001';
+const executionId = '00000000-0000-4000-8000-000000000002';
+const eventRef = '00000000-0000-4000-8000-000000000003';
+const deliveryId = '00000000-0000-4000-8000-000000000004';
+const receivedAt = '2026-08-31T12:00:00.000Z';
+
+describe('workflow execution event Agent Access schemas', () => {
+  test('accepts bounded summaries and serialized JSON detail', () => {
+    expect(listExecutionTriggerEventsResultSchema.safeParse(listResult()).success).toBe(true);
+    expect(
+      getExecutionTriggerEventResultSchema.safeParse({
+        ...summary(),
+        payload_preview: '{"action":"opened"}',
+      }).success,
+    ).toBe(true);
+  });
+
+  test('requires non-empty event references and preserves long lookup keys', () => {
+    const longEventRef = `${eventRef}${'x'.repeat(512)}`;
+
+    expect(
+      getExecutionTriggerEventInputSchema.safeParse({
+        job_id: jobId,
+        execution_id: executionId,
+        event_ref: longEventRef,
+      }).success,
+    ).toBe(true);
+    expect(
+      getExecutionTriggerEventInputSchema.safeParse({
+        job_id: jobId,
+        execution_id: executionId,
+        event_ref: '',
+      }).success,
+    ).toBe(false);
+    expect(getExecutionTriggerEventInputJsonSchema.properties.event_ref).toMatchObject({
+      minLength: 1,
+    });
+    expect(
+      getExecutionTriggerEventResultSchema.safeParse({
+        ...summary(),
+        event_ref: longEventRef,
+        payload_preview: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  test('uses the producer page default and rejects workspace-level input', () => {
+    expect(
+      listExecutionTriggerEventsInputSchema.parse({job_id: jobId, execution_id: executionId}),
+    ).toMatchObject({limit: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT});
+    expect(
+      listExecutionTriggerEventsInputSchema.safeParse({
+        job_id: jobId,
+        execution_id: executionId,
+        workspace_id: '00000000-0000-4000-8000-000000000005',
+      }).success,
+    ).toBe(false);
+  });
+
+  test('mirrors page, metadata, and preview bounds in JSON schemas', () => {
+    expect(listExecutionTriggerEventsResultJsonSchema.properties.trigger_events).toMatchObject({
+      type: 'array',
+      maxItems: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX,
+    });
+    expect(getExecutionTriggerEventResultJsonSchema.properties.payload_preview).toMatchObject({
+      anyOf: [
+        {
+          type: 'string',
+          maxLength: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES,
+          contentMediaType: 'application/json',
+        },
+        {type: 'null'},
+      ],
+    });
+  });
+
+  test('rejects clipped or invalid payload previews', () => {
+    const invalidPreviews = [
+      'not-json',
+      `{"body":"${'x'.repeat(AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES)}"}`,
+    ];
+    for (const payload_preview of invalidPreviews) {
+      expect(
+        getExecutionTriggerEventResultSchema.safeParse({...summary(), payload_preview}).success,
+      ).toBe(false);
+    }
+  });
+});
+
+function summary() {
+  return {
+    event_ref: eventRef,
+    delivery_id: deliveryId,
+    source: 'github',
+    event: 'push',
+    disposition: 'fire' as const,
+    outcome: 'consumed' as const,
+    outcome_reason: null,
+    received_at: receivedAt,
+    stored_payload_bytes: 32,
+    normalized_event_bytes: 128,
+  };
+}
+
+function listResult() {
+  return {
+    job_id: jobId,
+    execution_id: executionId,
+    trigger_events: [summary()],
+    next_cursor: null,
+    total: 1,
+  };
+}

package/src/schemas/workflow-execution-events.ts

@@ -0,0 +1,217 @@
+import {z} from 'zod';
+import type {AgentAccessObjectSchema} from './envelope.js';
+import {AGENT_ACCESS_PAGE_LIMIT_MAX, AGENT_ACCESS_TEXT_MAX_BYTES} from './paged-tools.js';
+import {dateTimeSchema, idSchema, utf8CappedString} from './primitives.js';
+
+/** Default page size for one execution's listener-event history. */
+export const AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT = 25;
+
+/** Maximum number of execution listener-event summaries in one page. */
+export const AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX = AGENT_ACCESS_PAGE_LIMIT_MAX;
+
+/** Maximum serialized UTF-8 size of one untrusted payload preview. */
+export const AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES = 16 * 1024;
+
+const textSchema = utf8CappedString(AGENT_ACCESS_TEXT_MAX_BYTES);
+const payloadPreviewSchema = utf8CappedString(
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES,
+).refine(isSerializedJson, {message: 'Payload preview must be serialized JSON'});
+
+const executionTriggerEventDispositionSchema = z.enum(['fire', 'resolve']);
+const executionTriggerEventOutcomeSchema = z.enum([
+  'pending',
+  'consumed',
+  'honored',
+  'rejected',
+  'abandoned',
+]);
+const executionTriggerEventOutcomeReasonSchema = z
+  .enum(['payload_too_large', 'until', 'timeout', 'max_executions', 'cancelled'])
+  .nullable();
+const eventRefSchema = z.string().min(1);
+
+const executionTriggerEventSummarySchema = z
+  .object({
+    event_ref: eventRefSchema,
+    delivery_id: textSchema,
+    source: textSchema,
+    event: textSchema,
+    disposition: executionTriggerEventDispositionSchema,
+    outcome: executionTriggerEventOutcomeSchema,
+    outcome_reason: executionTriggerEventOutcomeReasonSchema,
+    received_at: dateTimeSchema,
+    stored_payload_bytes: z.number().int().nonnegative(),
+    normalized_event_bytes: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const listExecutionTriggerEventsInputSchema = z
+  .object({
+    job_id: idSchema,
+    execution_id: idSchema,
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX)
+      .default(AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT),
+    cursor: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const getExecutionTriggerEventInputSchema = z
+  .object({
+    job_id: idSchema,
+    execution_id: idSchema,
+    event_ref: eventRefSchema,
+  })
+  .strict();
+
+export type ListExecutionTriggerEventsInputDto = z.output<
+  typeof listExecutionTriggerEventsInputSchema
+>;
+export type GetExecutionTriggerEventInputDto = z.output<typeof getExecutionTriggerEventInputSchema>;
+
+export const listExecutionTriggerEventsResultSchema = z
+  .object({
+    job_id: idSchema,
+    execution_id: idSchema,
+    trigger_events: z
+      .array(executionTriggerEventSummarySchema)
+      .max(AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX),
+    next_cursor: z.string().nullable(),
+    total: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export type ListExecutionTriggerEventsResultDto = z.infer<
+  typeof listExecutionTriggerEventsResultSchema
+>;
+
+export const getExecutionTriggerEventResultSchema = executionTriggerEventSummarySchema
+  .extend({
+    /** Serialized JSON text. It is untrusted data, not a typed workflow value. */
+    payload_preview: payloadPreviewSchema.nullable(),
+    payload_preview_truncated: z.literal(true).optional(),
+    payload_preview_total_bytes: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export type GetExecutionTriggerEventResultDto = z.infer<
+  typeof getExecutionTriggerEventResultSchema
+>;
+
+const uuid = {type: 'string', format: 'uuid'} as const;
+const dateTime = {type: 'string', format: 'date-time'} as const;
+const text = {type: 'string', maxLength: AGENT_ACCESS_TEXT_MAX_BYTES} as const;
+const eventRef = {type: 'string', minLength: 1} as const;
+const serializedJson = {
+  type: 'string',
+  maxLength: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES,
+  contentMediaType: 'application/json',
+} as const;
+const nullable = (schema: Record<string, unknown>) => ({anyOf: [schema, {type: 'null'}]}) as const;
+
+export const listExecutionTriggerEventsInputJsonSchema = {
+  type: 'object',
+  properties: {
+    job_id: uuid,
+    execution_id: uuid,
+    limit: {
+      type: 'integer',
+      minimum: 1,
+      maximum: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX,
+      default: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT,
+    },
+    cursor: {type: 'string', minLength: 1},
+  },
+  required: ['job_id', 'execution_id'],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+export const getExecutionTriggerEventInputJsonSchema = {
+  type: 'object',
+  properties: {job_id: uuid, execution_id: uuid, event_ref: eventRef},
+  required: ['job_id', 'execution_id', 'event_ref'],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+const executionTriggerEventSummaryJson = {
+  type: 'object',
+  properties: {
+    event_ref: eventRef,
+    delivery_id: text,
+    source: text,
+    event: text,
+    disposition: {type: 'string', enum: ['fire', 'resolve']},
+    outcome: {
+      type: 'string',
+      enum: ['pending', 'consumed', 'honored', 'rejected', 'abandoned'],
+    },
+    outcome_reason: {
+      anyOf: [
+        {
+          type: 'string',
+          enum: ['payload_too_large', 'until', 'timeout', 'max_executions', 'cancelled'],
+        },
+        {type: 'null'},
+      ],
+    },
+    received_at: dateTime,
+    stored_payload_bytes: {type: 'integer', minimum: 0},
+    normalized_event_bytes: {type: 'integer', minimum: 0},
+  },
+  required: [
+    'event_ref',
+    'delivery_id',
+    'source',
+    'event',
+    'disposition',
+    'outcome',
+    'outcome_reason',
+    'received_at',
+    'stored_payload_bytes',
+    'normalized_event_bytes',
+  ],
+  additionalProperties: false,
+} as const;
+
+const executionTriggerEventDetailJson = {
+  ...executionTriggerEventSummaryJson,
+  properties: {
+    ...executionTriggerEventSummaryJson.properties,
+    payload_preview: nullable(serializedJson),
+    payload_preview_truncated: {const: true},
+    payload_preview_total_bytes: {type: 'integer', minimum: 0},
+  },
+  required: [...executionTriggerEventSummaryJson.required, 'payload_preview'],
+} as const;
+
+export const listExecutionTriggerEventsResultJsonSchema = {
+  type: 'object',
+  properties: {
+    job_id: uuid,
+    execution_id: uuid,
+    trigger_events: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX,
+      items: executionTriggerEventSummaryJson,
+    },
+    next_cursor: nullable({type: 'string', minLength: 1}),
+    total: {type: 'integer', minimum: 0},
+  },
+  required: ['job_id', 'execution_id', 'trigger_events', 'next_cursor'],
+  additionalProperties: false,
+} as const satisfies AgentAccessObjectSchema;
+
+export const getExecutionTriggerEventResultJsonSchema =
+  executionTriggerEventDetailJson satisfies AgentAccessObjectSchema;
+
+function isSerializedJson(value: string): boolean {
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,202 @@
+import {
+  AGENT_ACCESS_WORKFLOW_EXECUTION_PAGE_LIMIT,
+  AGENT_ACCESS_WORKFLOW_JOB_PAGE_LIMIT,
+  AGENT_ACCESS_WORKFLOW_RUN_ATTEMPT_PAGE_LIMIT,
+  AGENT_ACCESS_WORKFLOW_STEP_ATTEMPT_PAGE_LIMIT,
+  AGENT_ACCESS_WORKFLOW_STEP_PAGE_LIMIT,
+  getWorkflowJobInputSchema,
+  getWorkflowJobResultJsonSchema,
+  getWorkflowJobResultSchema,
+  getWorkflowRunInputSchema,
+  getWorkflowRunResultJsonSchema,
+  getWorkflowRunResultSchema,
+  listWorkflowExecutionStepsInputSchema,
+  listWorkflowExecutionStepsResultJsonSchema,
+  listWorkflowExecutionStepsResultSchema,
+  listWorkflowJobExecutionsInputSchema,
+  listWorkflowJobExecutionsResultJsonSchema,
+  listWorkflowRunAttemptsInputSchema,
+  listWorkflowRunAttemptsResultJsonSchema,
+  listWorkflowRunJobsInputSchema,
+  listWorkflowRunJobsResultJsonSchema,
+  listWorkflowStepAttemptsInputSchema,
+  listWorkflowStepAttemptsResultJsonSchema,
+} from './workflow-tools.js';
+
+const runId = '00000000-0000-4000-8000-000000000001';
+const jobId = '00000000-0000-4000-8000-000000000002';
+const executionId = '00000000-0000-4000-8000-000000000003';
+const stepId = '00000000-0000-4000-8000-000000000004';
+const isoDate = '2026-08-01T00:00:00.000Z';
+
+describe('workflow agent-access schemas', () => {
+  test('uses producer page defaults and keeps workspace implicit', () => {
+    expect(listWorkflowRunAttemptsInputSchema.parse({run_id: runId}).limit).toBe(
+      AGENT_ACCESS_WORKFLOW_RUN_ATTEMPT_PAGE_LIMIT,
+    );
+    expect(listWorkflowRunJobsInputSchema.parse({run_id: runId, attempt: 2}).limit).toBe(
+      AGENT_ACCESS_WORKFLOW_JOB_PAGE_LIMIT,
+    );
+    expect(listWorkflowJobExecutionsInputSchema.parse({job_id: jobId}).limit).toBe(
+      AGENT_ACCESS_WORKFLOW_EXECUTION_PAGE_LIMIT,
+    );
+    expect(
+      listWorkflowExecutionStepsInputSchema.parse({job_id: jobId, execution_id: executionId}).limit,
+    ).toBe(AGENT_ACCESS_WORKFLOW_STEP_PAGE_LIMIT);
+    expect(listWorkflowStepAttemptsInputSchema.parse({step_id: stepId}).limit).toBe(
+      AGENT_ACCESS_WORKFLOW_STEP_ATTEMPT_PAGE_LIMIT,
+    );
+    expect(getWorkflowRunInputSchema.safeParse({run_id: runId, workspace_id: runId}).success).toBe(
+      false,
+    );
+    expect(getWorkflowJobInputSchema.safeParse({job_id: jobId, extra: true}).success).toBe(false);
+  });
+
+  test('requires the run attempt when listing jobs', () => {
+    expect(listWorkflowRunJobsInputSchema.safeParse({run_id: runId}).success).toBe(false);
+    expect(listWorkflowRunJobsInputSchema.safeParse({run_id: runId, attempt: 0}).success).toBe(
+      false,
+    );
+  });
+
+  test('declares one object result schema without embedded traversal children', () => {
+    const schemas = [
+      getWorkflowRunResultJsonSchema,
+      listWorkflowRunAttemptsResultJsonSchema,
+      listWorkflowRunJobsResultJsonSchema,
+      getWorkflowJobResultJsonSchema,
+      listWorkflowJobExecutionsResultJsonSchema,
+      listWorkflowExecutionStepsResultJsonSchema,
+      listWorkflowStepAttemptsResultJsonSchema,
+    ];
+    for (const schema of schemas) expect(schema).not.toHaveProperty('oneOf');
+
+    expect(getWorkflowRunResultJsonSchema.properties).not.toHaveProperty('jobs');
+    expect(getWorkflowJobResultJsonSchema.properties).toHaveProperty('selected_execution');
+    expect(listWorkflowExecutionStepsResultJsonSchema.properties.steps).toBeDefined();
+    expect(listWorkflowStepAttemptsResultJsonSchema.properties.attempts).toBeDefined();
+  });
+
+  test('rejects diagnostic and child collection fields from traversal results', () => {
+    const validRun = runResult();
+    expect(getWorkflowRunResultSchema.safeParse(validRun).success).toBe(true);
+    expect(getWorkflowRunResultSchema.safeParse({...validRun, jobs: []}).success).toBe(false);
+
+    const validJob = jobResult();
+    expect(getWorkflowJobResultSchema.safeParse(validJob).success).toBe(true);
+    expect(
+      getWorkflowJobResultSchema.safeParse({
+        ...validJob,
+        job: {...validJob.job, dependencies: []},
+      }).success,
+    ).toBe(false);
+
+    const validSteps = {
+      job_id: jobId,
+      execution_id: executionId,
+      steps: [stepResult()],
+      next_cursor: null,
+    };
+    expect(listWorkflowExecutionStepsResultSchema.safeParse(validSteps).success).toBe(true);
+    expect(
+      listWorkflowExecutionStepsResultSchema.safeParse({
+        ...validSteps,
+        steps: [{...stepResult(), attempts: {items: [], next_cursor: null}}],
+      }).success,
+    ).toBe(false);
+  });
+
+  test('enforces text caps by UTF-8 bytes', () => {
+    const validRun = runResult();
+    const underByteCap = {...validRun, name: `${'🙂'.repeat(127)}a`};
+    const overByteCap = {...validRun, name: '🙂'.repeat(129)};
+
+    expect(getWorkflowRunResultSchema.safeParse(underByteCap).success).toBe(true);
+    expect(getWorkflowRunResultSchema.safeParse(overByteCap).success).toBe(false);
+  });
+});
+
+function runResult() {
+  return {
+    id: runId,
+    project_id: runId,
+    definition_id: jobId,
+    number: 1,
+    name: 'Run',
+    workflow_name: 'Workflow',
+    status: 'failed' as const,
+    origin: 'synced' as const,
+    dev_source: null,
+    trigger_provider: 'github',
+    trigger_source: 'push',
+    trigger_event: 'push',
+    trigger_reference: {repository: 'shipfox/platform', ref: 'main', commit: 'abc', actor: 'noe'},
+    created_at: isoDate,
+    started_at: isoDate,
+    finished_at: isoDate,
+    attempt: {
+      id: executionId,
+      workflow_run_id: runId,
+      attempt: 1,
+      status: 'failed' as const,
+      created_at: isoDate,
+      started_at: isoDate,
+      finished_at: isoDate,
+      rerun_mode: null,
+    },
+    job_status_counts: [{status: 'failed' as const, count: 1}],
+    has_started_job_execution: true,
+  };
+}
+
+function jobResult() {
+  return {
+    workflow_run_id: runId,
+    workflow_run_attempt: 1,
+    job: {
+      id: jobId,
+      key: 'build',
+      name: 'Build',
+      position: 0,
+      status: 'failed' as const,
+      status_reason: 'step_failed' as const,
+      mode: 'one_shot' as const,
+      listener_status: 'inactive' as const,
+      carried_over: false,
+      execution_count: 1,
+      execution_status_counts: {pending: 0, running: 0, succeeded: 0, failed: 1, cancelled: 0},
+      default_execution: executionResult(),
+    },
+    selected_execution: {...executionResult(), has_context: true},
+  };
+}
+
+function executionResult() {
+  return {
+    id: executionId,
+    sequence: 1,
+    name: 'Build execution',
+    status: 'failed' as const,
+    display_status: 'failed' as const,
+    status_reason: 'step_failed' as const,
+    status_reason_message: 'The step failed',
+    queued_at: isoDate,
+    started_at: isoDate,
+    finished_at: isoDate,
+    timed_out_at: null,
+    updated_at: isoDate,
+  };
+}
+
+function stepResult() {
+  return {
+    id: stepId,
+    key: 'run',
+    name: 'Run command',
+    type: 'run' as const,
+    position: 0,
+    status: 'failed' as const,
+    status_reason: null,
+    current_attempt: 1,
+  };
+}