@shipfox/api-workflows 2.0.0

package/src/core/agent-tools.ts

@@ -0,0 +1,422 @@
+import type {
+  MaterializedAgentIntegrationConfigDto,
+  MaterializedAgentIntegrationToolConfigDto,
+} from '@shipfox/api-agent-dto';
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {
+  AgentToolCatalogEntry,
+  AgentToolCatalogMethod,
+  AgentToolCatalogs,
+  GetIntegrationConnectionByIdFn,
+  IntegrationProviderKind,
+  LoadWorkspaceConnectionSnapshot,
+  WorkspaceConnectionSnapshot,
+} from '@shipfox/api-integration-core';
+import {getProjectById} from '@shipfox/api-projects';
+import {AgentIntegrationMaterializationError} from './errors.js';
+
+type WorkflowModelJob = WorkflowModel['jobs'][number];
+type WorkflowModelAgentStep = Extract<WorkflowModelJob['steps'][number], {kind: 'agent'}>;
+type WorkflowModelStepIntegration = NonNullable<WorkflowModelAgentStep['integrations']>[number];
+
+interface AgentToolMaterializationServices {
+  readonly catalogs: AgentToolCatalogs;
+  readonly loadWorkspaceConnectionSnapshot: LoadWorkspaceConnectionSnapshot;
+  readonly getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export interface AgentToolMaterializationContext {
+  readonly catalogs: AgentToolCatalogs;
+  readonly workspaceConnectionSnapshot: WorkspaceConnectionSnapshot;
+  readonly defaultConnection: {
+    readonly id: string;
+    readonly slug: string;
+    readonly provider: IntegrationProviderKind;
+  };
+}
+
+export interface AgentToolMaterializationSnapshot {
+  readonly steps: readonly AgentToolMaterializationSnapshotStep[];
+}
+
+export interface AgentToolMaterializationSnapshotStep {
+  readonly jobKey: string;
+  readonly stepId: string;
+  readonly integrations: readonly MaterializedAgentIntegrationConfigDto[];
+}
+
+interface SelectedToolState {
+  readonly entry: AgentToolCatalogEntry;
+  readonly methods: Map<string, AgentToolCatalogMethod>;
+  selectedStandalone: boolean;
+}
+
+let services: AgentToolMaterializationServices | undefined;
+
+export function setAgentToolMaterializationServices(
+  nextServices: AgentToolMaterializationServices,
+): void {
+  services = nextServices;
+}
+
+export function clearAgentToolMaterializationServices(): void {
+  services = undefined;
+}
+
+export async function loadAgentToolMaterializationContext(params: {
+  readonly model: WorkflowModel | null;
+  readonly workspaceId: string;
+  readonly projectId: string;
+  readonly jobs?: readonly WorkflowModelJob[] | undefined;
+}): Promise<AgentToolMaterializationContext | undefined> {
+  if (!modelHasAgentStepIntegrations(params.model, params.jobs)) return undefined;
+  if (services === undefined) {
+    throw new AgentIntegrationMaterializationError('Agent tool materialization is not configured');
+  }
+
+  const project = await getProjectById(params.projectId);
+  if (project === undefined) {
+    throw new AgentIntegrationMaterializationError(
+      `Project ${params.projectId} was not found while materializing agent integrations`,
+    );
+  }
+
+  const [workspaceConnectionSnapshot, defaultConnection] = await Promise.all([
+    services.loadWorkspaceConnectionSnapshot(params.workspaceId),
+    services.getIntegrationConnectionById(project.sourceConnectionId),
+  ]);
+  if (defaultConnection === undefined) {
+    throw new AgentIntegrationMaterializationError(
+      `Source connection ${project.sourceConnectionId} was not found while materializing agent integrations`,
+    );
+  }
+
+  return {
+    catalogs: services.catalogs,
+    workspaceConnectionSnapshot,
+    defaultConnection: {
+      id: defaultConnection.id,
+      slug: defaultConnection.slug,
+      provider: defaultConnection.provider,
+    },
+  };
+}
+
+export function materializeAgentIntegrations(params: {
+  readonly jobKey: string;
+  readonly stepId: string;
+  readonly integrations: readonly WorkflowModelStepIntegration[] | undefined;
+  readonly context: AgentToolMaterializationContext | undefined;
+  readonly snapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}): MaterializedAgentIntegrationConfigDto[] | undefined {
+  const snapshot = findSnapshotStep(params);
+  if (snapshot !== undefined) return snapshot.integrations.map(copyMaterializedIntegration);
+  if (params.integrations === undefined) return undefined;
+  if (params.context === undefined) {
+    throw new AgentIntegrationMaterializationError(
+      'Agent integrations require materialization context',
+    );
+  }
+  const {context} = params;
+
+  return params.integrations.map((integration) =>
+    materializeAgentIntegration({integration, context}),
+  );
+}
+
+export function createAgentToolMaterializationSnapshot(params: {
+  readonly model: WorkflowModel;
+  readonly context: AgentToolMaterializationContext | undefined;
+}): AgentToolMaterializationSnapshot | null {
+  if (params.context === undefined) return null;
+
+  const steps = params.model.jobs.flatMap((job) =>
+    job.steps.flatMap((step) => {
+      if (step.kind !== 'agent' || step.integrations === undefined) return [];
+      const integrations = materializeAgentIntegrations({
+        jobKey: job.key,
+        stepId: step.id,
+        integrations: step.integrations,
+        context: params.context,
+      });
+      if (integrations === undefined) return [];
+      return [
+        {
+          jobKey: job.key,
+          stepId: step.id,
+          integrations,
+        },
+      ];
+    }),
+  );
+
+  return steps.length === 0 ? null : {steps};
+}
+
+function findSnapshotStep(params: {
+  readonly jobKey: string;
+  readonly stepId: string;
+  readonly snapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}): AgentToolMaterializationSnapshotStep | undefined {
+  return params.snapshot?.steps.find(
+    (step) => step.jobKey === params.jobKey && step.stepId === params.stepId,
+  );
+}
+
+function materializeAgentIntegration(params: {
+  readonly integration: WorkflowModelStepIntegration;
+  readonly context: AgentToolMaterializationContext;
+}): MaterializedAgentIntegrationConfigDto {
+  const connection = resolveConnection(params);
+  const catalog = params.context.catalogs.get(connection.provider);
+  if (catalog === undefined) {
+    throw new AgentIntegrationMaterializationError(
+      `Integration provider ${connection.provider} has no agent tool catalog`,
+    );
+  }
+
+  const tools = selectTools({
+    catalog,
+    include: params.integration.include,
+    exclude: params.integration.exclude ?? [],
+  });
+  const requiredScope = mergeRequiredScopes(tools.map((tool) => tool.requiredScope));
+
+  return {
+    connectionId: connection.id,
+    connectionSlug: connection.slug,
+    provider: connection.provider,
+    requiredScope,
+    tools,
+  };
+}
+
+function copyMaterializedIntegration(
+  integration: MaterializedAgentIntegrationConfigDto,
+): MaterializedAgentIntegrationConfigDto {
+  return {
+    ...integration,
+    requiredScope: [...integration.requiredScope],
+    tools: integration.tools.map((tool) => ({
+      ...tool,
+      requiredScope: [...tool.requiredScope],
+      ...(tool.methods === undefined
+        ? {}
+        : {
+            methods: tool.methods.map((method) => ({
+              ...method,
+              requiredScope: [...method.requiredScope],
+            })),
+          }),
+    })),
+  };
+}
+
+function resolveConnection(params: {
+  readonly integration: WorkflowModelStepIntegration;
+  readonly context: AgentToolMaterializationContext;
+}): AgentToolMaterializationContext['defaultConnection'] {
+  if (params.integration.connection === undefined) return params.context.defaultConnection;
+
+  const connection = params.context.workspaceConnectionSnapshot.get(params.integration.connection);
+  if (connection === undefined) {
+    throw new AgentIntegrationMaterializationError(
+      `Integration connection ${params.integration.connection} was not found while materializing agent integrations`,
+    );
+  }
+  return {
+    id: connection.id,
+    slug: params.integration.connection,
+    provider: connection.provider,
+  };
+}
+
+function selectTools(params: {
+  readonly catalog: readonly AgentToolCatalogEntry[];
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+}): MaterializedAgentIntegrationToolConfigDto[] {
+  const selected = new Map<string, SelectedToolState>();
+
+  for (const token of params.include) {
+    applySelection({catalog: params.catalog, selected, token, mode: 'include'});
+  }
+  for (const token of params.exclude) {
+    applySelection({catalog: params.catalog, selected, token, mode: 'exclude'});
+  }
+
+  const tools = params.catalog.flatMap((entry) => {
+    const state = selected.get(entry.id);
+    if (state === undefined) return [];
+    return [materializedTool(state)];
+  });
+  if (tools.length === 0) {
+    throw new AgentIntegrationMaterializationError(
+      'Agent integration selection resolved to no tools',
+    );
+  }
+  return tools;
+}
+
+function applySelection(params: {
+  readonly catalog: readonly AgentToolCatalogEntry[];
+  readonly selected: Map<string, SelectedToolState>;
+  readonly token: string;
+  readonly mode: 'include' | 'exclude';
+}): void {
+  if (params.token === '*') {
+    for (const entry of params.catalog) applyEntrySelection(params, entry);
+    return;
+  }
+
+  const match = findCatalogSelection(params.catalog, params.token);
+  if (match === undefined) {
+    throw new AgentIntegrationMaterializationError(`Unknown integration tool: ${params.token}`);
+  }
+  applyEntrySelection(params, match.entry, match.method);
+}
+
+function applyEntrySelection(
+  params: {
+    readonly selected: Map<string, SelectedToolState>;
+    readonly token: string;
+    readonly mode: 'include' | 'exclude';
+  },
+  entry: AgentToolCatalogEntry,
+  method?: AgentToolCatalogMethod | undefined,
+): void {
+  if (params.mode === 'exclude') {
+    excludeEntrySelection(params.selected, entry, method);
+    return;
+  }
+
+  const state =
+    params.selected.get(entry.id) ??
+    ({entry, methods: new Map(), selectedStandalone: false} satisfies SelectedToolState);
+  if (entry.methods === undefined) {
+    state.selectedStandalone = true;
+  } else if (method === undefined) {
+    for (const candidate of entry.methods) state.methods.set(candidate.id, candidate);
+  } else {
+    state.methods.set(method.id, method);
+  }
+  params.selected.set(entry.id, state);
+}
+
+function excludeEntrySelection(
+  selected: Map<string, SelectedToolState>,
+  entry: AgentToolCatalogEntry,
+  method?: AgentToolCatalogMethod | undefined,
+): void {
+  if (method === undefined) {
+    selected.delete(entry.id);
+    return;
+  }
+
+  const state = selected.get(entry.id);
+  if (state === undefined) return;
+  state.methods.delete(method.id);
+  if (!state.selectedStandalone && state.methods.size === 0) selected.delete(entry.id);
+}
+
+function findCatalogSelection(
+  catalog: readonly AgentToolCatalogEntry[],
+  token: string,
+):
+  | {readonly entry: AgentToolCatalogEntry; readonly method?: AgentToolCatalogMethod | undefined}
+  | undefined {
+  const entry = catalog.find((candidate) => candidate.id === token);
+  if (entry !== undefined) return {entry};
+
+  const wildcardSuffix = '.*';
+  if (token.endsWith(wildcardSuffix)) {
+    const family = token.slice(0, -wildcardSuffix.length);
+    const familyEntry = catalog.find((candidate) => candidate.id === family);
+    return familyEntry === undefined ? undefined : {entry: familyEntry};
+  }
+
+  const dotIndex = token.indexOf('.');
+  if (dotIndex < 1) return undefined;
+  const family = token.slice(0, dotIndex);
+  const methodId = token.slice(dotIndex + 1);
+  const familyEntry = catalog.find((candidate) => candidate.id === family);
+  const method = familyEntry?.methods?.find((candidate) => candidate.id === methodId);
+  if (familyEntry === undefined || method === undefined) return undefined;
+  return {entry: familyEntry, method};
+}
+
+function materializedTool(state: SelectedToolState): MaterializedAgentIntegrationToolConfigDto {
+  if (state.entry.methods === undefined) {
+    return {
+      id: state.entry.id,
+      sensitivity: state.entry.sensitivity,
+      sensitive: state.entry.sensitive,
+      requiredScope: normalizeRequiredScope(state.entry.requiredScope),
+      inputSchema: state.entry.inputSchema,
+      ...(state.entry.outputSchema === undefined ? {} : {outputSchema: state.entry.outputSchema}),
+    };
+  }
+
+  const methods = state.entry.methods
+    .filter((method) => state.methods.has(method.id))
+    .map((method) => ({
+      id: method.id,
+      token: `${state.entry.id}.${method.id}`,
+      description: method.description,
+      sensitivity: method.sensitivity,
+      sensitive: method.sensitive,
+      requiredScope: normalizeRequiredScope(method.requiredScope),
+    }));
+
+  return {
+    id: state.entry.id,
+    sensitivity: methods.some((method) => method.sensitivity === 'write') ? 'write' : 'read',
+    sensitive: methods.some((method) => method.sensitive),
+    requiredScope: mergeRequiredScopes(methods.map((method) => method.requiredScope)),
+    inputSchema: state.entry.inputSchema,
+    ...(state.entry.outputSchema === undefined ? {} : {outputSchema: state.entry.outputSchema}),
+    methods,
+  };
+}
+
+function mergeRequiredScopes(scopes: readonly unknown[]): unknown[] {
+  const items = scopes.flatMap(normalizeRequiredScope);
+  if (items.every(isPermissionScope)) {
+    const byPermission = new Map<string, 'read' | 'write'>();
+    for (const item of items) {
+      const existing = byPermission.get(item.permission);
+      if (existing === 'write') continue;
+      byPermission.set(item.permission, item.access);
+    }
+    return [...byPermission.entries()].map(([permission, access]) => ({permission, access}));
+  }
+
+  const deduped = new Map<string, unknown>();
+  for (const item of items) deduped.set(JSON.stringify(item), item);
+  return [...deduped.values()];
+}
+
+function normalizeRequiredScope(scope: unknown): unknown[] {
+  return Array.isArray(scope) ? [...scope] : [scope];
+}
+
+function isPermissionScope(
+  value: unknown,
+): value is {permission: string; access: 'read' | 'write'} {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as {permission?: unknown; access?: unknown};
+  return (
+    typeof candidate.permission === 'string' &&
+    (candidate.access === 'read' || candidate.access === 'write')
+  );
+}
+
+function modelHasAgentStepIntegrations(
+  model: WorkflowModel | null,
+  jobs: readonly WorkflowModelJob[] | undefined,
+): boolean {
+  if (model === null) return false;
+  return (jobs ?? model.jobs).some((job) =>
+    job.steps.some((step) => step.kind === 'agent' && step.integrations !== undefined),
+  );
+}

package/src/core/checkout.test.ts

@@ -0,0 +1,112 @@
+import type {CheckoutSpec, IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {getProjectById} from '@shipfox/api-projects';
+import * as workflowRuns from '#db/workflow-runs.js';
+import {jobFactory} from '#test/factories/job.js';
+import {projectFactory} from '#test/factories/project.js';
+import {createJobCheckoutSpec, resolveCheckoutIntent} from './checkout.js';
+import {
+  CheckoutIntentUnresolvedError,
+  JobNotFoundError,
+  WorkflowRunNotFoundError,
+} from './errors.js';
+
+vi.mock('@shipfox/api-projects', () => ({getProjectById: vi.fn()}));
+const mockGetProjectById = vi.mocked(getProjectById);
+
+describe('resolveCheckoutIntent', () => {
+  it('resolves connection + repo from the project, using the project workspace', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+
+    const intent = await resolveCheckoutIntent(job.id);
+
+    expect(intent).toEqual({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      persistCredentials: true,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('throws JobNotFoundError for an unknown job', async () => {
+    const act = resolveCheckoutIntent(crypto.randomUUID());
+
+    await expect(act).rejects.toBeInstanceOf(JobNotFoundError);
+  });
+
+  it('resolves the checkout target while the parent job projection is still pending', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create(
+      {},
+      {transient: {projectId: project.id, status: 'pending'}},
+    );
+
+    const intent = await resolveCheckoutIntent(job.id);
+
+    expect(intent.connectionId).toBe(project.sourceConnectionId);
+  });
+
+  it('throws WorkflowRunNotFoundError when the run is missing', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    vi.spyOn(workflowRuns, 'getWorkflowRunByAttemptId').mockResolvedValue(undefined);
+
+    const act = resolveCheckoutIntent(job.id);
+
+    await expect(act).rejects.toBeInstanceOf(WorkflowRunNotFoundError);
+  });
+
+  it('throws CheckoutIntentUnresolvedError when the project is missing', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(undefined);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+
+    const act = resolveCheckoutIntent(job.id);
+
+    await expect(act).rejects.toBeInstanceOf(CheckoutIntentUnresolvedError);
+  });
+});
+
+describe('createJobCheckoutSpec', () => {
+  it('passes the resolved intent and an undefined ref to the service', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    const spec: CheckoutSpec = {repositoryUrl: 'https://github.com/acme/repo.git', ref: 'main'};
+    const createCheckoutSpec = vi.fn().mockResolvedValue(spec);
+    const sourceControl = {createCheckoutSpec} as unknown as IntegrationSourceControlService;
+
+    const result = await createJobCheckoutSpec({jobId: job.id, sourceControl});
+
+    expect(result).toEqual({spec, persistCredentials: true});
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: undefined,
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('passes requested write contents permission to the service', async () => {
+    const project = projectFactory.build();
+    mockGetProjectById.mockResolvedValue(project);
+    const job = await jobFactory.create(
+      {},
+      {transient: {projectId: project.id, checkout: {permissions: {contents: 'write'}}}},
+    );
+    const spec: CheckoutSpec = {repositoryUrl: 'https://github.com/acme/repo.git', ref: 'main'};
+    const createCheckoutSpec = vi.fn().mockResolvedValue(spec);
+    const sourceControl = {createCheckoutSpec} as unknown as IntegrationSourceControlService;
+
+    await createJobCheckoutSpec({jobId: job.id, sourceControl});
+
+    expect(createCheckoutSpec).toHaveBeenCalledWith(
+      expect.objectContaining({permissions: {contents: 'write'}}),
+    );
+  });
+});

package/src/core/checkout.ts

@@ -0,0 +1,63 @@
+import type {CheckoutSpec, IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {getProjectById} from '@shipfox/api-projects';
+import {getJobById, getWorkflowRunByAttemptId} from '#db/workflow-runs.js';
+import {
+  CheckoutIntentUnresolvedError,
+  JobNotFoundError,
+  WorkflowRunNotFoundError,
+} from './errors.js';
+
+export interface CheckoutIntent {
+  workspaceId: string;
+  connectionId: string;
+  externalRepositoryId: string;
+  persistCredentials: boolean;
+  permissions: {contents: 'read' | 'write'};
+}
+
+/**
+ * Resolves what to check out for a job, keyed off the authoritative `jobId`
+ * (`workflowRunId`/`workflowRunAttemptId`/`workspaceId` in the lease claim are informational).
+ * Chain: job → attempt → run → project source metadata. Credential-free.
+ */
+export async function resolveCheckoutIntent(jobId: string): Promise<CheckoutIntent> {
+  const job = await getJobById(jobId);
+  if (!job) throw new JobNotFoundError(jobId);
+
+  const run = await getWorkflowRunByAttemptId(job.workflowRunAttemptId);
+  if (!run) throw new WorkflowRunNotFoundError(job.workflowRunAttemptId);
+
+  const project = await getProjectById(run.projectId);
+  if (!project) throw new CheckoutIntentUnresolvedError(run.projectId);
+
+  return {
+    workspaceId: project.workspaceId,
+    connectionId: project.sourceConnectionId,
+    externalRepositoryId: project.sourceExternalRepositoryId,
+    persistCredentials: job.checkout.persistCredentials,
+    permissions: job.checkout.permissions,
+  };
+}
+
+/**
+ * Resolves the job's checkout intent and exchanges it for a short-lived,
+ * scoped checkout spec. `ref` is left undefined so the provider defaults to the
+ * repository's default branch.
+ */
+export async function createJobCheckoutSpec({
+  jobId,
+  sourceControl,
+}: {
+  jobId: string;
+  sourceControl: IntegrationSourceControlService;
+}): Promise<{spec: CheckoutSpec; persistCredentials: boolean}> {
+  const intent = await resolveCheckoutIntent(jobId);
+  const spec = await sourceControl.createCheckoutSpec({
+    workspaceId: intent.workspaceId,
+    connectionId: intent.connectionId,
+    externalRepositoryId: intent.externalRepositoryId,
+    ref: undefined,
+    permissions: intent.permissions,
+  });
+  return {spec, persistCredentials: intent.persistCredentials};
+}

package/src/core/condition-trace.ts

@@ -0,0 +1,64 @@
+import {
+  type AvailabilitySite,
+  capTraceEntries,
+  evaluationTraceEntry,
+  predicateTraceEntry,
+  type RoutedExpression,
+  type WorkflowExpression,
+} from '@shipfox/expression';
+import type {PersistedEvaluationTraceEntry} from './entities/step.js';
+
+const DEFAULT_JOB_CONDITION_SOURCE = 'needs.all(n, n.status == "succeeded")';
+const DEFAULT_STEP_CONDITION_SOURCE = '!execution.failed';
+
+export function explicitConditionTrace(params: {
+  readonly expression: WorkflowExpression;
+  readonly field: 'job.if' | 'step.if';
+  readonly route: RoutedExpression;
+  readonly site: AvailabilitySite;
+  readonly value: boolean;
+  readonly degraded: boolean;
+}): readonly PersistedEvaluationTraceEntry[] {
+  return capTraceEntries([
+    {
+      ...predicateTraceEntry({
+        expression: params.expression.source,
+        route: params.route,
+        site: params.site,
+        value: params.value,
+        degraded: params.degraded,
+      }),
+      field: params.field,
+    },
+  ]);
+}
+
+export function defaultJobConditionTrace(): readonly PersistedEvaluationTraceEntry[] {
+  return capTraceEntries([
+    {
+      ...evaluationTraceEntry({
+        expression: DEFAULT_JOB_CONDITION_SOURCE,
+        roots: ['needs'],
+        fillTarget: 'job-activation',
+        evaluatedAt: 'job-activation',
+        value: 'false',
+      }),
+      field: 'job.default_gate',
+    },
+  ]);
+}
+
+export function defaultStepConditionTrace(): readonly PersistedEvaluationTraceEntry[] {
+  return capTraceEntries([
+    {
+      ...evaluationTraceEntry({
+        expression: DEFAULT_STEP_CONDITION_SOURCE,
+        roots: ['execution'],
+        fillTarget: 'step-dispatch',
+        evaluatedAt: 'step-dispatch',
+        value: 'false',
+      }),
+      field: 'step.default_gate',
+    },
+  ]);
+}

package/src/core/entities/index.ts

@@ -0,0 +1,9 @@
+export type {Job, JobCheckout, JobStatus} from './job.js';
+export type {Step, StepStatus} from './step.js';
+export type {
+  TriggerPayload,
+  WorkflowRun,
+  WorkflowRunStatus,
+  WorkflowSourceSnapshot,
+} from './workflow-run.js';
+export type {RerunMode, WorkflowRunAttempt} from './workflow-run-attempt.js';

package/src/core/entities/job-execution.ts

@@ -0,0 +1,32 @@
+import type {JobStatus, JobStatusReason} from './job.js';
+import type {PersistedEvaluationTraceEntry} from './step.js';
+
+export type JobExecutionStatus = Exclude<JobStatus, 'skipped'>;
+
+export interface WorkflowExecutionEvent {
+  source: string;
+  event: string;
+  delivery_id: string;
+  received_at: string;
+  data: unknown;
+}
+
+export interface JobExecution {
+  id: string;
+  jobId: string;
+  sequence: number;
+  name: string;
+  runner: string[] | null;
+  status: JobExecutionStatus;
+  statusReason: JobStatusReason | null;
+  triggerEvents: WorkflowExecutionEvent[];
+  outputs: Record<string, unknown> | null;
+  evaluationTrace?: readonly PersistedEvaluationTraceEntry[] | null;
+  version: number;
+  createdAt: Date;
+  updatedAt: Date;
+  queuedAt: Date | null;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+  timedOutAt: Date | null;
+}