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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-agent-access-dto",
   "license": "MIT",
-  "version": "21.0.0",
+  "version": "21.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -31,7 +31,8 @@
     }
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@shipfox/api-logs-dto": "20.0.0"
   },
   "devDependencies": {
     "@shipfox/biome": "1.10.1",

package/src/index.ts

@@ -29,6 +29,19 @@ export {
   agentAccessErrorSchema,
   agentAccessOutputSchema,
 } from './schemas/envelope.js';
+export {
+  AGENT_ACCESS_LOG_ATTEMPT_MAX,
+  AGENT_ACCESS_LOG_CONTENT_MAX_BYTES,
+  AGENT_ACCESS_LOG_SECTION_MAX_ITEMS,
+  AGENT_ACCESS_LOG_TAIL_LINES_DEFAULT,
+  AGENT_ACCESS_LOG_TAIL_LINES_MAX,
+  type GetStepLogsInputDto,
+  type GetStepLogsResultDto,
+  getStepLogsInputJsonSchema,
+  getStepLogsInputSchema,
+  getStepLogsResultJsonSchema,
+  getStepLogsResultSchema,
+} from './schemas/log-tools.js';
 export {
   AGENT_ACCESS_ANNOTATION_BODY_MAX_BYTES,
   AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES,
@@ -71,3 +84,103 @@ export {
   listWorkflowRunsResultJsonSchema,
   listWorkflowRunsResultSchema,
 } from './schemas/paged-tools.js';
+export {
+  AGENT_ACCESS_WORKFLOW_DIAGNOSTIC_VALUE_MAX_BYTES,
+  AGENT_ACCESS_WORKFLOW_SOURCE_MAX_BYTES,
+  type AgentAccessOversizedFieldDto,
+  type AgentAccessWorkflowDiagnosticFieldDto,
+  agentAccessOversizedFieldSchema,
+  agentAccessWorkflowDiagnosticFieldSchema,
+  type GetStepAttemptInputDto,
+  type GetStepAttemptResultDto,
+  type GetWorkflowExecutionContextInputDto,
+  type GetWorkflowExecutionContextResultDto,
+  type GetWorkflowRunSourceInputDto,
+  type GetWorkflowRunSourceResultDto,
+  getStepAttemptInputJsonSchema,
+  getStepAttemptInputSchema,
+  getStepAttemptResultJsonSchema,
+  getStepAttemptResultSchema,
+  getWorkflowExecutionContextInputJsonSchema,
+  getWorkflowExecutionContextInputSchema,
+  getWorkflowExecutionContextResultJsonSchema,
+  getWorkflowExecutionContextResultSchema,
+  getWorkflowRunSourceInputJsonSchema,
+  getWorkflowRunSourceInputSchema,
+  getWorkflowRunSourceResultJsonSchema,
+  getWorkflowRunSourceResultSchema,
+  type ListWorkflowRunJobExplanationsInputDto,
+  type ListWorkflowRunJobExplanationsResultDto,
+  listWorkflowRunJobExplanationsInputJsonSchema,
+  listWorkflowRunJobExplanationsInputSchema,
+  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,
+  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,
+  type GetWorkflowJobInputDto,
+  type GetWorkflowJobResultDto,
+  type GetWorkflowRunInputDto,
+  type GetWorkflowRunResultDto,
+  getWorkflowJobInputJsonSchema,
+  getWorkflowJobInputSchema,
+  getWorkflowJobResultJsonSchema,
+  getWorkflowJobResultSchema,
+  getWorkflowRunInputJsonSchema,
+  getWorkflowRunInputSchema,
+  getWorkflowRunResultJsonSchema,
+  getWorkflowRunResultSchema,
+  type ListWorkflowExecutionStepsInputDto,
+  type ListWorkflowExecutionStepsResultDto,
+  type ListWorkflowJobExecutionsInputDto,
+  type ListWorkflowJobExecutionsResultDto,
+  type ListWorkflowRunAttemptsInputDto,
+  type ListWorkflowRunAttemptsResultDto,
+  type ListWorkflowRunJobsInputDto,
+  type ListWorkflowRunJobsResultDto,
+  type ListWorkflowStepAttemptsInputDto,
+  type ListWorkflowStepAttemptsResultDto,
+  listWorkflowExecutionStepsInputJsonSchema,
+  listWorkflowExecutionStepsInputSchema,
+  listWorkflowExecutionStepsResultJsonSchema,
+  listWorkflowExecutionStepsResultSchema,
+  listWorkflowJobExecutionsInputJsonSchema,
+  listWorkflowJobExecutionsInputSchema,
+  listWorkflowJobExecutionsResultJsonSchema,
+  listWorkflowJobExecutionsResultSchema,
+  listWorkflowRunAttemptsInputJsonSchema,
+  listWorkflowRunAttemptsInputSchema,
+  listWorkflowRunAttemptsResultJsonSchema,
+  listWorkflowRunAttemptsResultSchema,
+  listWorkflowRunJobsInputJsonSchema,
+  listWorkflowRunJobsInputSchema,
+  listWorkflowRunJobsResultJsonSchema,
+  listWorkflowRunJobsResultSchema,
+  listWorkflowStepAttemptsInputJsonSchema,
+  listWorkflowStepAttemptsInputSchema,
+  listWorkflowStepAttemptsResultJsonSchema,
+  listWorkflowStepAttemptsResultSchema,
+} from './schemas/workflow-tools.js';

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

@@ -4,6 +4,7 @@ import {
   AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES,
   AGENT_ACCESS_TEXT_MAX_BYTES,
 } from './paged-tools.js';
+import {dateTimeSchema, idSchema, utf8CappedString} from './primitives.js';
 
 export const AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES = 16 * 1024;
 export const AGENT_ACCESS_TRIGGER_DECISION_MAX_ITEMS = 50;
@@ -11,18 +12,6 @@ export const AGENT_ACCESS_TRIGGER_REPLAY_MAX_ITEMS = 20;
 export const AGENT_ACCESS_FACET_MAX_ITEMS = 50;
 export const AGENT_ACCESS_FACET_VALUE_MAX_BYTES = 256;
 
-const idSchema = z.string().uuid();
-const dateTimeSchema = z.string().datetime();
-const utf8Encoder = new TextEncoder();
-
-const utf8CappedString = (maxBytes: number) =>
-  z
-    .string()
-    .max(maxBytes)
-    .refine((value) => utf8Encoder.encode(value).byteLength <= maxBytes, {
-      message: `String must contain at most ${maxBytes} UTF-8 bytes`,
-    });
-
 const textSchema = utf8CappedString(AGENT_ACCESS_TEXT_MAX_BYTES);
 const shortTextSchema = utf8CappedString(AGENT_ACCESS_CONNECTION_NAME_MAX_BYTES);
 const serializedJsonSchema = utf8CappedString(AGENT_ACCESS_SERIALIZED_JSON_MAX_BYTES).refine(
@@ -39,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,
@@ -146,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/log-tools.ts

@@ -0,0 +1,209 @@
+import {
+  DEFAULT_STEP_LOG_TAIL_LINES,
+  MAX_STEP_LOG_TAIL_LINES,
+} from '@shipfox/api-logs-dto/inter-module';
+import {z} from 'zod';
+import type {AgentAccessObjectSchema} from './envelope.js';
+import {idSchema, utf8CappedString} from './primitives.js';
+
+export const AGENT_ACCESS_LOG_CONTENT_MAX_BYTES = 64 * 1024;
+export const AGENT_ACCESS_LOG_SECTION_MAX_ITEMS = 10;
+export const AGENT_ACCESS_LOG_TAIL_LINES_DEFAULT = DEFAULT_STEP_LOG_TAIL_LINES;
+export const AGENT_ACCESS_LOG_TAIL_LINES_MAX = MAX_STEP_LOG_TAIL_LINES;
+export const AGENT_ACCESS_LOG_ATTEMPT_MAX = 2_147_483_647;
+
+const attemptSchema = z.number().int().min(1).max(AGENT_ACCESS_LOG_ATTEMPT_MAX);
+const tailLinesSchema = z
+  .number()
+  .int()
+  .min(1)
+  .max(AGENT_ACCESS_LOG_TAIL_LINES_MAX)
+  .default(AGENT_ACCESS_LOG_TAIL_LINES_DEFAULT);
+const contentSchema = utf8CappedString(AGENT_ACCESS_LOG_CONTENT_MAX_BYTES);
+
+export const getStepLogsInputSchema = z
+  .object({
+    step_id: idSchema.optional(),
+    run_id: idSchema.optional(),
+    attempt: attemptSchema.optional(),
+    failed_only: z.literal(true).optional(),
+    tail_lines: tailLinesSchema,
+  })
+  .superRefine((value, context) => {
+    const hasStep = value.step_id !== undefined;
+    const hasRun = value.run_id !== undefined;
+
+    if (hasStep === hasRun) {
+      context.addIssue({
+        code: 'custom',
+        path: [hasStep ? 'run_id' : 'step_id'],
+        message: 'Provide exactly one of step_id or run_id',
+      });
+    }
+    if (hasRun && value.failed_only !== true) {
+      context.addIssue({
+        code: 'custom',
+        path: ['failed_only'],
+        message: 'run_id requires failed_only to be true',
+      });
+    }
+    if (hasStep && value.failed_only !== undefined) {
+      context.addIssue({
+        code: 'custom',
+        path: ['failed_only'],
+        message: 'failed_only is only valid with run_id',
+      });
+    }
+    if (hasRun && value.attempt !== undefined) {
+      context.addIssue({
+        code: 'custom',
+        path: ['attempt'],
+        message: 'attempt is only valid with step_id',
+      });
+    }
+  })
+  .strict();
+
+export type GetStepLogsInputDto = z.output<typeof getStepLogsInputSchema>;
+
+const logSectionSchema = z
+  .object({
+    workflow_run_id: idSchema.optional(),
+    workflow_run_attempt: attemptSchema.optional(),
+    job_id: idSchema.optional(),
+    job_execution_id: idSchema.optional(),
+    step_id: idSchema,
+    step_attempt_id: idSchema.optional(),
+    attempt: attemptSchema,
+    content: contentSchema,
+    total_lines: z.number().int().nonnegative().optional(),
+    content_truncated: z.literal(true).optional(),
+    content_total_bytes: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export const getStepLogsResultSchema = z
+  .object({
+    run_id: idSchema.optional(),
+    workflow_run_attempt: attemptSchema.optional(),
+    sections: z.array(logSectionSchema).max(AGENT_ACCESS_LOG_SECTION_MAX_ITEMS),
+  })
+  .superRefine((value, context) => {
+    const hasRun = value.run_id !== undefined;
+    const hasRunAttempt = value.workflow_run_attempt !== undefined;
+
+    if (hasRun !== hasRunAttempt) {
+      context.addIssue({
+        code: 'custom',
+        path: [hasRun ? 'workflow_run_attempt' : 'run_id'],
+        message: 'run_id and workflow_run_attempt must be provided together',
+      });
+    }
+    if (!hasRun && value.sections.length !== 1) {
+      context.addIssue({
+        code: 'custom',
+        path: ['sections'],
+        message: 'A direct step read must contain exactly one section',
+      });
+    }
+  })
+  .strict();
+
+export type GetStepLogsResultDto = z.output<typeof getStepLogsResultSchema>;
+
+const uuid = {type: 'string', format: 'uuid'} as const;
+const attempt = {
+  type: 'integer',
+  minimum: 1,
+  maximum: AGENT_ACCESS_LOG_ATTEMPT_MAX,
+} as const;
+
+const directInputJsonSchema = {
+  type: 'object',
+  properties: {
+    step_id: uuid,
+    attempt,
+    tail_lines: {
+      type: 'integer',
+      minimum: 1,
+      maximum: AGENT_ACCESS_LOG_TAIL_LINES_MAX,
+      default: AGENT_ACCESS_LOG_TAIL_LINES_DEFAULT,
+    },
+  },
+  required: ['step_id'],
+  additionalProperties: false,
+} as const;
+
+const failedOnlyInputJsonSchema = {
+  type: 'object',
+  properties: {
+    run_id: uuid,
+    failed_only: {const: true},
+    tail_lines: {
+      type: 'integer',
+      minimum: 1,
+      maximum: AGENT_ACCESS_LOG_TAIL_LINES_MAX,
+      default: AGENT_ACCESS_LOG_TAIL_LINES_DEFAULT,
+    },
+  },
+  required: ['run_id', 'failed_only'],
+  additionalProperties: false,
+} as const;
+
+export const getStepLogsInputJsonSchema = {
+  type: 'object',
+  oneOf: [directInputJsonSchema, failedOnlyInputJsonSchema],
+} as const satisfies AgentAccessObjectSchema;
+
+const logSectionJsonSchema = {
+  type: 'object',
+  properties: {
+    workflow_run_id: uuid,
+    workflow_run_attempt: attempt,
+    job_id: uuid,
+    job_execution_id: uuid,
+    step_id: uuid,
+    step_attempt_id: uuid,
+    attempt,
+    content: {type: 'string', maxLength: AGENT_ACCESS_LOG_CONTENT_MAX_BYTES},
+    total_lines: {type: 'integer', minimum: 0},
+    content_truncated: {const: true},
+    content_total_bytes: {type: 'integer', minimum: 0},
+  },
+  required: ['step_id', 'attempt', 'content'],
+  additionalProperties: false,
+} as const;
+
+const directResultJsonSchema = {
+  type: 'object',
+  properties: {
+    sections: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 1,
+      items: logSectionJsonSchema,
+    },
+  },
+  required: ['sections'],
+  additionalProperties: false,
+} as const;
+
+const aggregateResultJsonSchema = {
+  type: 'object',
+  properties: {
+    run_id: uuid,
+    workflow_run_attempt: attempt,
+    sections: {
+      type: 'array',
+      maxItems: AGENT_ACCESS_LOG_SECTION_MAX_ITEMS,
+      items: logSectionJsonSchema,
+    },
+  },
+  required: ['run_id', 'workflow_run_attempt', 'sections'],
+  additionalProperties: false,
+} as const;
+
+export const getStepLogsResultJsonSchema = {
+  type: 'object',
+  oneOf: [directResultJsonSchema, aggregateResultJsonSchema],
+} as const satisfies AgentAccessObjectSchema;

package/src/schemas/paged-tools.ts

@@ -1,5 +1,6 @@
 import {z} from 'zod';
 import type {AgentAccessObjectSchema} from './envelope.js';
+import {dateTimeSchema, idSchema, utf8CappedString} from './primitives.js';
 
 export const AGENT_ACCESS_DEFAULT_PAGE_LIMIT = 50;
 export const AGENT_ACCESS_PAGE_LIMIT_MAX = 100;
@@ -12,16 +13,6 @@ export const AGENT_ACCESS_DIAGNOSTIC_PATH_MAX_BYTES = 512;
 export const AGENT_ACCESS_DIAGNOSTIC_MAX_ITEMS = 10;
 export const AGENT_ACCESS_ANNOTATION_BODY_MAX_BYTES = 8 * 1024;
 
-const idSchema = z.string().uuid();
-const dateTimeSchema = z.string().datetime();
-const utf8Encoder = new TextEncoder();
-const utf8CappedString = (maxBytes: number) =>
-  z
-    .string()
-    .max(maxBytes)
-    .refine((value) => utf8Encoder.encode(value).byteLength <= maxBytes, {
-      message: `String must contain at most ${maxBytes} UTF-8 bytes`,
-    });
 const pageInputFields = {
   limit: z
     .number()

package/src/schemas/primitives.ts

@@ -0,0 +1,14 @@
+import {z} from 'zod';
+
+export const idSchema = z.string().uuid();
+export const dateTimeSchema = z.string().datetime();
+
+const utf8Encoder = new TextEncoder();
+
+export const utf8CappedString = (maxBytes: number) =>
+  z
+    .string()
+    .max(maxBytes)
+    .refine((value) => utf8Encoder.encode(value).byteLength <= maxBytes, {
+      message: `String must contain at most ${maxBytes} UTF-8 bytes`,
+    });