@shipfox/api-workflows 11.0.0 → 12.0.0

package/src/core/listener-execution-materialization.ts

@@ -1,4 +1,5 @@
 import type {WorkflowModel} from '@shipfox/api-definitions-dto';
+import {evaluationTraceEntry} from '@shipfox/expression';
 import type {AgentDefaultsResolver} from './agent-defaults.js';
 import type {
   AgentToolMaterializationContext,
@@ -31,7 +32,9 @@ export interface MaterializeListenerExecutionParams {
   readonly run: Pick<
     WorkflowRun,
     | 'id'
+    | 'number'
     | 'name'
+    | 'workflowName'
     | 'definitionId'
     | 'projectId'
     | 'workspaceId'
@@ -39,7 +42,9 @@ export interface MaterializeListenerExecutionParams {
     | 'triggerPayload'
     | 'inputs'
   >;
-  readonly job: Pick<Job, 'id' | 'key'>;
+  readonly job: Pick<Job, 'id' | 'key'> & Partial<Pick<Job, 'name'>>;
+  readonly vars?: Record<string, string> | undefined;
+  readonly variableResolutionError?: InterpolationUnresolvableError | undefined;
   readonly sequence: number;
   readonly triggerEvents: readonly WorkflowExecutionEvent[];
   readonly priorExecutions: readonly JobExecution[];
@@ -49,7 +54,7 @@ export interface MaterializeListenerExecutionParams {
 }
 
 export interface MaterializedListenerExecution {
-  readonly name: string;
+  readonly nameOverride: string | null;
   readonly runner: readonly string[];
   readonly status: JobExecutionStatus;
   readonly statusReason: 'unknown' | null;
@@ -61,14 +66,18 @@ export interface MaterializedListenerExecution {
 export async function materializeListenerExecution(
   params: MaterializeListenerExecutionParams,
 ): Promise<MaterializedListenerExecution> {
-  const fallbackName = `${params.job.key} #${params.sequence}`;
-  let executionName = fallbackName;
+  let executionName = params.job.name ?? params.job.key;
+  let nameOverride: string | null = null;
   let evaluationTrace: readonly PersistedEvaluationTraceEntry[] = [];
   let runner: readonly string[] = [];
   let steps: readonly MaterializedWorkflowStep[] = [];
   let status: JobExecutionStatus = 'pending';
+  if (params.variableResolutionError) {
+    evaluationTrace = [variableResolutionTrace(params.variableResolutionError)];
+  }
 
   try {
+    if (params.variableResolutionError) throw params.variableResolutionError;
     if (!params.model) throw new PermanentListenerMaterializationError('Run attempt has no model');
     const modelJob = params.model.jobs.find((job) => job.key === params.job.key);
     if (!modelJob) {
@@ -77,16 +86,34 @@ export async function materializeListenerExecution(
       );
     }
 
+    const materializationJob = {
+      ...params.job,
+      name: params.job.name ?? modelJob.name ?? null,
+    };
+    executionName = materializationJob.name ?? params.job.key;
+
     const resolvedName = resolveJobExecutionName({
       definitionId: params.run.definitionId,
       job: modelJob,
-      fallbackName,
-      context: listenerExecutionContext({...params, executionName, status}).values,
+      context: listenerExecutionContext({
+        ...params,
+        job: materializationJob,
+        nameOverride: null,
+        executionName,
+        status,
+      }).values,
     });
-    executionName = resolvedName.value;
+    nameOverride = resolvedName.nameOverride;
+    executionName = nameOverride ?? executionName;
     evaluationTrace = resolvedName.trace;
 
-    const context = listenerExecutionContext({...params, executionName, status});
+    const context = listenerExecutionContext({
+      ...params,
+      job: materializationJob,
+      nameOverride,
+      executionName,
+      status,
+    });
     runner = materializeJobRunner({
       job: modelJob,
       context,
@@ -109,7 +136,7 @@ export async function materializeListenerExecution(
   }
 
   return {
-    name: executionName,
+    nameOverride,
     runner,
     status,
     statusReason: status === 'failed' ? 'unknown' : null,
@@ -119,12 +146,29 @@ export async function materializeListenerExecution(
   };
 }
 
+function variableResolutionTrace(
+  error: InterpolationUnresolvableError,
+): PersistedEvaluationTraceEntry {
+  return {
+    ...evaluationTraceEntry({
+      expression: error.source,
+      roots: ['vars'],
+      fillTarget: 'execution-creation',
+      evaluatedAt: 'execution-creation',
+      degraded: true,
+    }),
+    field: error.field,
+    ...(error.envKey === undefined ? {} : {envKey: error.envKey}),
+  };
+}
+
 function listenerExecutionContext(
   params: Pick<
     MaterializeListenerExecutionParams,
-    'run' | 'job' | 'sequence' | 'triggerEvents' | 'priorExecutions'
+    'run' | 'job' | 'vars' | 'sequence' | 'triggerEvents' | 'priorExecutions'
   > & {
     readonly executionName: string;
+    readonly nameOverride: string | null;
     readonly status: JobExecutionStatus;
   },
 ) {
@@ -132,8 +176,10 @@ function listenerExecutionContext(
     run: params.run,
     triggerPayload: params.run.triggerPayload,
     inputs: params.run.inputs,
-    jobId: params.job.id,
+    vars: params.vars,
+    job: {...params.job, name: params.job.name ?? null},
     sequence: params.sequence,
+    nameOverride: params.nameOverride,
     executionName: params.executionName,
     status: params.status,
     triggerEvents: params.triggerEvents,

package/src/core/resolve-trigger-reference.test.ts

@@ -0,0 +1,160 @@
+import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {TriggerPayload} from './entities/workflow-run.js';
+import {resolveWorkflowRunTriggerReference} from './resolve-trigger-reference.js';
+
+describe('resolveWorkflowRunTriggerReference', () => {
+  const workspaceId = crypto.randomUUID();
+  const connectionId = crypto.randomUUID();
+
+  it.each([
+    {
+      event: 'push',
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    },
+    {
+      event: 'pull_request',
+      externalRepositoryId: 'github:43',
+      ref: 'refs/pull/12/head',
+    },
+  ])('resolves the normalized %s trigger facts with its project', async (reference) => {
+    const integrations = {
+      resolveTriggerReference: vi.fn().mockResolvedValue({
+        externalRepositoryId: reference.externalRepositoryId,
+        ref: reference.ref,
+        commit: 'a'.repeat(40),
+        actor: 'octocat',
+      }),
+      resolveSourceRepository: vi.fn().mockResolvedValue({
+        connection: {id: connectionId, provider: 'github', slug: 'github-main'},
+        repository: {
+          externalRepositoryId: reference.externalRepositoryId,
+          owner: 'acme',
+          name: 'api',
+          fullName: 'acme/api',
+          defaultBranch: 'main',
+          visibility: 'private' as const,
+          cloneUrl: 'https://github.com/acme/api.git',
+          htmlUrl: 'https://github.com/acme/api',
+        },
+      }),
+    } as unknown as IntegrationsModuleClient;
+    const projects = {
+      getProjectBySource: vi.fn().mockResolvedValue({project: {id: 'project-1'}}),
+    } as unknown as ProjectsModuleClient;
+    const triggerPayload: TriggerPayload = {
+      provider: 'github',
+      source: 'github-main',
+      event: reference.event,
+      deliveryId: 'delivery-1',
+      data: {event: reference.event},
+    };
+
+    await expect(
+      resolveWorkflowRunTriggerReference({
+        workspaceId,
+        triggerConnectionId: connectionId,
+        triggerPayload,
+        integrations,
+        projects,
+      }),
+    ).resolves.toEqual({
+      project: {id: 'project-1'},
+      repository: 'acme/api',
+      ref: reference.ref,
+      commit: 'a'.repeat(40),
+      actor: 'octocat',
+    });
+    expect(projects.getProjectBySource).toHaveBeenCalledWith({
+      workspaceId,
+      sourceConnectionId: connectionId,
+      sourceExternalRepositoryId: reference.externalRepositoryId,
+    });
+  });
+
+  it('returns null for a provider event without a source-control reference', async () => {
+    const resolveTriggerReference = vi.fn().mockResolvedValue(null);
+    const resolveSourceRepository = vi.fn();
+    const integrations = {
+      resolveTriggerReference,
+      resolveSourceRepository,
+    } as unknown as IntegrationsModuleClient;
+    const projects = {
+      getProjectBySource: vi.fn(),
+    } as unknown as ProjectsModuleClient;
+
+    await expect(
+      resolveWorkflowRunTriggerReference({
+        workspaceId,
+        triggerConnectionId: connectionId,
+        triggerPayload: {
+          provider: 'linear',
+          source: 'linear-main',
+          event: 'Issue.create',
+          deliveryId: 'delivery-1',
+          data: {type: 'Issue'},
+        },
+        integrations,
+        projects,
+      }),
+    ).resolves.toBeNull();
+    expect(resolveSourceRepository).not.toHaveBeenCalled();
+    expect(projects.getProjectBySource).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    'trigger reference',
+    'project lookup',
+    'source repository lookup',
+  ] as const)('returns null when %s fails during enrichment', async (failure) => {
+    const integrations = {
+      resolveTriggerReference:
+        failure === 'trigger reference'
+          ? vi.fn().mockRejectedValue(new Error('trigger reference unavailable'))
+          : vi.fn().mockResolvedValue({
+              externalRepositoryId: 'github:42',
+              ref: 'refs/heads/main',
+              commit: 'a'.repeat(40),
+            }),
+      resolveSourceRepository:
+        failure === 'source repository lookup'
+          ? vi.fn().mockRejectedValue(new Error('source repository unavailable'))
+          : vi.fn().mockResolvedValue({
+              connection: {id: connectionId, provider: 'github', slug: 'github-main'},
+              repository: {
+                externalRepositoryId: 'github:42',
+                owner: 'acme',
+                name: 'api',
+                fullName: 'acme/api',
+                defaultBranch: 'main',
+                visibility: 'private' as const,
+                cloneUrl: 'https://github.com/acme/api.git',
+                htmlUrl: 'https://github.com/acme/api',
+              },
+            }),
+    } as unknown as IntegrationsModuleClient;
+    const projects = {
+      getProjectBySource:
+        failure === 'project lookup'
+          ? vi.fn().mockRejectedValue(new Error('project lookup unavailable'))
+          : vi.fn().mockResolvedValue({project: {id: 'project-1'}}),
+    } as unknown as ProjectsModuleClient;
+
+    await expect(
+      resolveWorkflowRunTriggerReference({
+        workspaceId,
+        triggerConnectionId: connectionId,
+        triggerPayload: {
+          provider: 'github',
+          source: 'github-main',
+          event: 'push',
+          deliveryId: 'delivery-1',
+          data: {event: 'push'},
+        },
+        integrations,
+        projects,
+      }),
+    ).resolves.toBeNull();
+  });
+});

package/src/core/resolve-trigger-reference.ts

@@ -0,0 +1,53 @@
+import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {TriggerPayload, WorkflowRunTriggerReference} from './entities/workflow-run.js';
+
+export async function resolveWorkflowRunTriggerReference(params: {
+  workspaceId: string;
+  triggerConnectionId?: string | undefined;
+  triggerPayload: TriggerPayload;
+  integrations?: IntegrationsModuleClient | undefined;
+  projects?: ProjectsModuleClient | undefined;
+}): Promise<WorkflowRunTriggerReference | null> {
+  if (
+    params.triggerConnectionId === undefined ||
+    !('data' in params.triggerPayload) ||
+    params.integrations === undefined ||
+    params.projects === undefined
+  ) {
+    return null;
+  }
+
+  try {
+    const reference = await params.integrations.resolveTriggerReference({
+      workspaceId: params.workspaceId,
+      connectionId: params.triggerConnectionId,
+      payload: params.triggerPayload.data,
+    });
+    if (reference === null) return null;
+
+    const [projectResult, sourceResult] = await Promise.all([
+      params.projects.getProjectBySource({
+        workspaceId: params.workspaceId,
+        sourceConnectionId: params.triggerConnectionId,
+        sourceExternalRepositoryId: reference.externalRepositoryId,
+      }),
+      params.integrations.resolveSourceRepository({
+        workspaceId: params.workspaceId,
+        connectionId: params.triggerConnectionId,
+        externalRepositoryId: reference.externalRepositoryId,
+      }),
+    ]);
+
+    return {
+      project: projectResult.project === null ? null : {id: projectResult.project.id},
+      repository: `${sourceResult.repository.owner}/${sourceResult.repository.name}`,
+      ref: reference.ref,
+      commit: reference.commit,
+      actor: reference.actor,
+    };
+  } catch {
+    // Trigger metadata is best-effort and must not block run creation.
+    return null;
+  }
+}

package/src/core/run-workflow.ts

@@ -15,6 +15,7 @@ export interface RunWorkflowParams {
   projectId: string;
   definitionId: string;
   triggerPayload: TriggerPayload;
+  triggerConnectionId?: string | undefined;
   inputs?: Record<string, unknown> | undefined;
   triggerIdempotencyKey?: string | undefined;
   integrations?: IntegrationsModuleClient | undefined;
@@ -47,6 +48,7 @@ export async function runWorkflow(
     name: definition.name,
     model,
     triggerPayload: params.triggerPayload,
+    triggerConnectionId: params.triggerConnectionId,
     inputs: params.inputs,
     sourceSnapshot: definition.sourceSnapshot,
     triggerIdempotencyKey: params.triggerIdempotencyKey,

package/src/core/step-config/agent.ts

@@ -42,6 +42,7 @@ interface AgentFieldResolutions {
   readonly prompt: FieldResolution;
   readonly model: FieldResolution | undefined;
   readonly provider: FieldResolution | undefined;
+  readonly thinking: FieldResolution | undefined;
   readonly hasTemplates: boolean;
 }
 
@@ -72,9 +73,11 @@ export async function resolveAgentStepConfig(
 
   if (usesAuthoredMode) return authoredAgentStepConfig(params.step, fields);
 
-  const hasDeferredModelOrProvider =
-    fields.model?.kind === 'residual' || fields.provider?.kind === 'residual';
-  if (hasDeferredModelOrProvider) return deferredAgentStepConfig(params, fields);
+  const hasDeferredAgentField =
+    fields.model?.kind === 'residual' ||
+    fields.provider?.kind === 'residual' ||
+    fields.thinking?.kind === 'residual';
+  if (hasDeferredAgentField) return deferredAgentStepConfig(params, fields);
 
   return await agentStepConfigWithDefaults(params.step, params, fields);
 }
@@ -119,7 +122,10 @@ export async function completeAgentConfig(params: {
     harness: agent.harness ?? readConfigHarness(params.config),
     provider,
     model,
-    thinking: agent.thinking ?? readConfigThinking(params.config),
+    thinking:
+      agent.thinking === undefined
+        ? readConfigThinking(params.config)
+        : completeAgentField({field: 'agent.thinking', template: agent.thinking, params}),
     resolveAgentDefaults: params.resolveAgentDefaults,
     definitionId: params.definitionId,
   });
@@ -138,7 +144,7 @@ export async function completeAgentConfig(params: {
 }
 
 function completeAgentField(args: {
-  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider';
+  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider' | 'agent.thinking';
   readonly template: ResolvedField;
   readonly params: {
     readonly context: WorkflowEvaluationContext;
@@ -161,7 +167,7 @@ export async function completeAgentDefaults(params: {
   readonly harness: WorkflowModelAgentStep['harness'] | undefined;
   readonly provider: string | undefined;
   readonly model: string | undefined;
-  readonly thinking: AgentThinking | undefined;
+  readonly thinking: string | undefined;
   readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
   readonly definitionId: string;
 }): Promise<ResolvedAgentDefaults> {
@@ -218,12 +224,23 @@ function resolveAgentFields(params: ResolveAgentStepConfigParams): AgentFieldRes
     trace,
     definitionId: params.definitionId,
   });
+  const thinking = resolveOptionalAgentField({
+    field: 'agent.thinking',
+    value: params.step.thinking,
+    template: params.step.templates?.thinking,
+    context: params.context,
+    mode: params.mode,
+    diagnostics,
+    trace,
+    definitionId: params.definitionId,
+  });
   const hasTemplates =
     params.step.templates?.prompt !== undefined ||
     params.step.templates?.model !== undefined ||
-    params.step.templates?.provider !== undefined;
+    params.step.templates?.provider !== undefined ||
+    params.step.templates?.thinking !== undefined;
 
-  return {diagnostics, trace, prompt, model, provider, hasTemplates};
+  return {diagnostics, trace, prompt, model, provider, thinking, hasTemplates};
 }
 
 function authoredAgentStepConfig(
@@ -260,7 +277,7 @@ function deferredAgentStepConfig(
         ...(fields.model === undefined ? {} : {model: dispatchPlanField(fields.model)}),
         ...(fields.provider === undefined ? {} : {provider: dispatchPlanField(fields.provider)}),
         ...(step.harness === undefined ? {} : {harness: step.harness}),
-        ...(step.thinking === undefined ? {} : {thinking: step.thinking}),
+        ...(fields.thinking === undefined ? {} : {thinking: dispatchPlanField(fields.thinking)}),
         ...agentToolsConfig(step),
         ...materializedAgentIntegrationsConfig(params),
       },
@@ -284,7 +301,7 @@ async function agentStepConfigWithDefaults(
     harness: step.harness,
     provider: providerValue,
     model: modelValue,
-    thinking: step.thinking,
+    thinking: frozenFieldValue(fields.thinking),
     resolveAgentDefaults: params.resolveAgentDefaults,
     definitionId: params.definitionId,
   });
@@ -384,7 +401,7 @@ function frozenFieldValue(field: FieldResolution | undefined): string | undefine
 }
 
 function resolveAgentField(params: {
-  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider';
+  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider' | 'agent.thinking';
   readonly value: string;
   readonly template: ResolvedField['segments'] | undefined;
   readonly context: WorkflowEvaluationContext;
@@ -414,7 +431,7 @@ function resolveAgentField(params: {
 }
 
 function resolveOptionalAgentField(params: {
-  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider';
+  readonly field: 'agent.prompt' | 'agent.model' | 'agent.provider' | 'agent.thinking';
   readonly value: string | undefined;
   readonly template: ResolvedField['segments'] | undefined;
   readonly context: WorkflowEvaluationContext;