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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-agent-access-dto",
   "license": "MIT",
-  "version": "21.1.0",
+  "version": "21.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/index.ts

@@ -116,6 +116,23 @@ export {
   listWorkflowRunJobExplanationsResultJsonSchema,
   listWorkflowRunJobExplanationsResultSchema,
 } from './schemas/workflow-diagnostics.js';
+export {
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_LIMIT,
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PAGE_MAX,
+  AGENT_ACCESS_EXECUTION_TRIGGER_EVENT_PREVIEW_MAX_BYTES,
+  type GetExecutionTriggerEventInputDto,
+  type GetExecutionTriggerEventResultDto,
+  getExecutionTriggerEventInputJsonSchema,
+  getExecutionTriggerEventInputSchema,
+  getExecutionTriggerEventResultJsonSchema,
+  getExecutionTriggerEventResultSchema,
+  type ListExecutionTriggerEventsInputDto,
+  type ListExecutionTriggerEventsResultDto,
+  listExecutionTriggerEventsInputJsonSchema,
+  listExecutionTriggerEventsInputSchema,
+  listExecutionTriggerEventsResultJsonSchema,
+  listExecutionTriggerEventsResultSchema,
+} from './schemas/workflow-execution-events.js';
 export {
   AGENT_ACCESS_WORKFLOW_ATTEMPT_MAX,
   AGENT_ACCESS_WORKFLOW_EXECUTION_COUNT_MAX,

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

@@ -0,0 +1,43 @@
+import {getTriggerEventResultJsonSchema, getTriggerEventResultSchema} from './diagnostic-tools.js';
+
+const eventId = '00000000-0000-4000-8000-000000000001';
+
+describe('diagnostic agent-access schemas', () => {
+  test('accepts filtered trigger decisions in runtime and JSON schemas', () => {
+    const result = {
+      id: eventId,
+      origin: 'integration',
+      provider: 'github',
+      source: 'github',
+      event: 'push',
+      outcome: 'discarded',
+      matched_count: 0,
+      connection_id: null,
+      connection_name: null,
+      replay_of_event_id: null,
+      received_at: '2026-09-04T12:00:00.000Z',
+      processed_at: '2026-09-04T12:00:01.000Z',
+      payload_preview: '{}',
+      decisions: [
+        {
+          id: '00000000-0000-4000-8000-000000000002',
+          subscription_kind: 'trigger',
+          outcome: 'filtered',
+          reason: null,
+          workflow_definition_id: '00000000-0000-4000-8000-000000000003',
+          project_id: '00000000-0000-4000-8000-000000000004',
+          workflow_run_id: null,
+          job_id: null,
+        },
+      ],
+      decisions_total_count: 1,
+      replays: [],
+      replays_total_count: 0,
+    };
+
+    expect(getTriggerEventResultSchema.safeParse(result).success).toBe(true);
+    expect(
+      getTriggerEventResultJsonSchema.properties.decisions.items.properties.outcome.enum,
+    ).toContain('filtered');
+  });
+});

package/src/schemas/diagnostic-tools.ts

@@ -28,7 +28,13 @@ export type GetTriggerEventFacetsInputDto = z.infer<typeof getTriggerEventFacets
 
 const triggerOriginSchema = z.enum(['integration', 'manual', 'cron', 'dev']);
 const triggerOutcomeSchema = z.enum(['received', 'routed', 'discarded', 'failed', 'errored']);
-const triggerDecisionOutcomeSchema = z.enum(['triggered', 'filter-error', 'dispatch-error']);
+const triggerDecisionOutcomeSchema = z.enum([
+  'triggered',
+  'filtered',
+  'filter-error',
+  'dispatch-error',
+  'rejected',
+]);
 const triggerDecisionSchema = z
   .object({
     id: idSchema,
@@ -135,7 +141,10 @@ const triggerDecisionJsonSchema = {
   properties: {
     id: uuid,
     subscription_kind: {type: 'string', enum: ['trigger', 'listener', 'dev']},
-    outcome: {type: 'string', enum: ['triggered', 'filter-error', 'dispatch-error']},
+    outcome: {
+      type: 'string',
+      enum: ['triggered', 'filtered', 'filter-error', 'dispatch-error', 'rejected'],
+    },
     reason: nullable(text),
     workflow_definition_id: nullable(uuid),
     project_id: nullable(uuid),

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;
+  }
+}