@shipfox/api-workflows 11.0.0 → 12.0.0

package/src/core/step-config/complete-step-dispatch-config.test.ts

@@ -9,6 +9,7 @@ import {
 import {agentInterModuleContract} from '@shipfox/api-agent-dto/inter-module';
 import {parseWorkflowTemplate, planInterpolationField} from '@shipfox/expression';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
+import {agentThinkingSchema} from '@shipfox/workflow-document';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import type {Step} from '#core/entities/step.js';
 import {AgentConfigUnresolvableError, InterpolationUnresolvableError} from '#core/errors.js';
@@ -68,7 +69,7 @@ const resolveAgentDefaults: AgentDefaultsResolver = (params) => ({
   harness: params.harness ?? 'pi',
   provider: params.provider ?? 'openai',
   model: params.model ?? 'gpt-5.5',
-  thinking: params.thinking ?? 'off',
+  thinking: agentThinkingSchema.safeParse(params.thinking).data ?? 'off',
 });
 
 function materializedIntegration(): MaterializedAgentIntegrationConfigDto {
@@ -251,6 +252,128 @@ describe('completeStepDispatchConfig', () => {
     });
   });
 
+  it('resolves a deferred working directory at step dispatch', async () => {
+    const pending = step({
+      config: {},
+      configPlan: {
+        working_directory: plannedField(template('steps.build.outputs.path')),
+      },
+    });
+
+    const result = await completeStepDispatchConfig({
+      step: pending,
+      context: {
+        ...context,
+        values: {
+          ...context.values,
+          steps: {
+            build: {
+              outputs: {path: 'packages/api'},
+            },
+          },
+        },
+      },
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result).toEqual({
+      config: {working_directory: 'packages/api'},
+      trace: [
+        {
+          expression: 'steps.build.outputs.path',
+          roots: ['steps'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          value: 'packages/api',
+          field: 'step.working_directory',
+        },
+      ],
+    });
+  });
+
+  it('resolves deferred checkout targets at step dispatch', async () => {
+    const pending = step({
+      type: 'checkout',
+      config: {
+        checkout: {
+          fetch_depth: 1,
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+        },
+      },
+      configPlan: {
+        checkout: {
+          repository: plannedField(template('steps.build.outputs.repository')),
+          ref: plannedField(template('steps.build.outputs.ref')),
+        },
+      },
+    });
+
+    const result = await completeStepDispatchConfig({
+      step: pending,
+      context: {
+        ...context,
+        values: {
+          ...context.values,
+          steps: {
+            build: {
+              outputs: {repository: 'acme/api', ref: 'refs/heads/main'},
+            },
+          },
+        },
+      },
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result).toEqual({
+      config: {
+        checkout: {
+          fetch_depth: 1,
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+          repository: 'acme/api',
+          ref: 'refs/heads/main',
+        },
+      },
+      trace: [
+        {
+          expression: 'steps.build.outputs.repository',
+          roots: ['steps'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          value: 'acme/api',
+          field: 'checkout.repository',
+        },
+        {
+          expression: 'steps.build.outputs.ref',
+          roots: ['steps'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          value: 'refs/heads/main',
+          field: 'checkout.ref',
+        },
+      ],
+    });
+  });
+
+  it('rejects invalid resolved working directories', async () => {
+    const pending = step({
+      config: {working_directory: '../outside'},
+      configPlan: null,
+    });
+
+    await expect(
+      completeStepDispatchConfig({
+        step: pending,
+        context,
+        resolveAgentDefaults,
+        definitionId: 'def-1',
+      }),
+    ).rejects.toThrow('Invalid working_directory');
+  });
+
   it('completes deferred agent config with the resolved harness', async () => {
     const integration = materializedIntegration();
     const mcpServers = integrationMcpServers([integration]);
@@ -306,7 +429,7 @@ describe('completeStepDispatchConfig', () => {
       configPlan: {
         agent: {
           harness: 'claude',
-          thinking: 'off',
+          thinking: plannedField('off'),
           prompt: plannedField(`Review ${template('steps.build.outputs.sha')}`),
         },
       },

package/src/core/step-config/complete-step-dispatch-config.ts

@@ -1,7 +1,10 @@
+import {WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS} from '@shipfox/api-definitions-dto';
+import {assertWorkingDirectory} from '@shipfox/api-workflows-dto';
 import {capTraceEntries} from '@shipfox/expression';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import type {PersistedEvaluationTraceEntry, Step} from '#core/entities/step.js';
 import {completeAgentConfig} from './agent.js';
+import {completeStepFieldWithTrace} from './fields.js';
 import {completeRunDispatchConfig} from './run.js';
 import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
 
@@ -15,7 +18,10 @@ export async function completeStepDispatchConfig(params: {
   readonly trace: readonly PersistedEvaluationTraceEntry[];
 }> {
   const plan = params.step.configPlan;
-  if (plan === null) return {config: params.step.config, trace: []};
+  if (plan === null) {
+    assertWorkingDirectoryIfPresent(params.step.config.working_directory);
+    return {config: params.step.config, trace: []};
+  }
 
   const config = {...params.step.config};
   delete config.secret_bindings;
@@ -35,6 +41,82 @@ export async function completeStepDispatchConfig(params: {
     definitionId: params.definitionId,
     trace,
   });
+  completeWorkingDirectoryConfig({
+    config,
+    plan,
+    context: params.context,
+    definitionId: params.definitionId,
+    trace,
+  });
+  completeCheckoutConfig({
+    config,
+    plan,
+    context: params.context,
+    definitionId: params.definitionId,
+    trace,
+  });
+  assertWorkingDirectoryIfPresent(config.working_directory);
 
   return {config, trace: capTraceEntries(trace)};
 }
+
+function completeCheckoutConfig(params: {
+  readonly config: Record<string, unknown>;
+  readonly plan: Step['configPlan'] & object;
+  readonly context: WorkflowEvaluationContext;
+  readonly definitionId: string;
+  readonly trace: PersistedEvaluationTraceEntry[];
+}): void {
+  const checkoutPlan = params.plan.checkout;
+  if (checkoutPlan === undefined) return;
+
+  const checkout = params.config.checkout;
+  if (checkout === null || typeof checkout !== 'object' || Array.isArray(checkout)) {
+    throw new Error('Checkout dispatch config is missing an object');
+  }
+
+  const resolvedCheckout = {...checkout} as Record<string, unknown>;
+  params.config.checkout = resolvedCheckout;
+
+  for (const [key, fieldName] of WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS) {
+    const field = checkoutPlan[key];
+    if (field === undefined) continue;
+
+    const resolved = completeStepFieldWithTrace({
+      field: fieldName,
+      template: field,
+      context: params.context,
+      definitionId: params.definitionId,
+      errorField: fieldName,
+    });
+    resolvedCheckout[key] = resolved.value;
+    params.trace.push(...resolved.trace.map((entry) => ({...entry, field: fieldName})));
+  }
+}
+
+function assertWorkingDirectoryIfPresent(value: unknown): void {
+  if (value !== undefined) assertWorkingDirectory(value);
+}
+
+function completeWorkingDirectoryConfig(params: {
+  readonly config: Record<string, unknown>;
+  readonly plan: Step['configPlan'] & object;
+  readonly context: WorkflowEvaluationContext;
+  readonly definitionId: string;
+  readonly trace: PersistedEvaluationTraceEntry[];
+}): void {
+  const field = params.plan.working_directory;
+  if (field === undefined) return;
+
+  const resolved = completeStepFieldWithTrace({
+    field: 'step.working_directory',
+    template: field,
+    context: params.context,
+    definitionId: params.definitionId,
+    errorField: 'step.working_directory',
+  });
+  params.config.working_directory = resolved.value;
+  params.trace.push(
+    ...resolved.trace.map((entry) => ({...entry, field: 'step.working_directory' as const})),
+  );
+}

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

@@ -38,4 +38,11 @@ export {
   resolveJobExecutionName,
 } from './resolve-job-execution-name.js';
 export type {WorkflowStepTemplateDiagnostic} from './resolve-step-config.js';
+export {
+  type ResolveWorkflowRunNameResult,
+  resolveWorkflowRunName,
+  sanitizeWorkflowDisplayText,
+  type WorkflowRunNameDegradation,
+  type WorkflowRunNameResolutionCause,
+} from './resolve-workflow-run-name.js';
 export type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';

package/src/core/step-config/materialize-job-execution-steps.test.ts

@@ -5,6 +5,7 @@ import {
   AGENT_INTEGRATION_MCP_TRANSPORT,
 } from '@shipfox/api-agent-dto';
 import {agentInterModuleContract} from '@shipfox/api-agent-dto/inter-module';
+import {createWorkflowExpression} from '@shipfox/expression';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import type {AgentToolCatalogEntry, AgentToolMaterializationContext} from '#core/agent-tools.js';
@@ -31,6 +32,19 @@ function shellRef(name: string): string {
   return `\${${name}}`;
 }
 
+function checkout(repository: string) {
+  return {
+    repository,
+    fetchDepth: 1,
+    permissions: {contents: 'read' as const},
+    persistCredentials: true,
+  };
+}
+
+function condition(source: string) {
+  return createWorkflowExpression({source, check: {mode: 'syntax'}});
+}
+
 function jobExecutionContext(): WorkflowEvaluationContext {
   return {
     site: 'execution-creation',
@@ -58,6 +72,10 @@ function jobExecutionContext(): WorkflowEvaluationContext {
             event: 'pull_request_review',
             delivery_id: 'delivery-2',
             received_at: '2026-06-30T12:01:00.000Z',
+            project: null,
+            repository: null,
+            ref: null,
+            commit: null,
             data: {body: 'LGTM'},
           },
         ],
@@ -157,6 +175,232 @@ function githubAgentToolCatalog(): readonly AgentToolCatalogEntry[] {
 }
 
 describe('materializeJobExecutionSteps', () => {
+  it('resolves static job names through the job execution context', async () => {
+    const model = workflowModel({
+      jobs: {
+        review: {
+          name: 'Review',
+          steps: [{name: template('job.name'), run: 'echo review'}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[1]).toMatchObject({
+      name: 'Review',
+      config: {run: 'echo review'},
+    });
+  });
+
+  it('materializes checkout steps with their resolved config and default name', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [
+            {
+              checkout: {
+                repository: 'acme/api',
+                ref: 'refs/heads/main',
+                fetchDepth: 0,
+                path: 'target',
+                permissions: {contents: 'write'},
+                persistCredentials: false,
+                force: true,
+              },
+            },
+          ],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({
+      type: 'setup',
+      config: {},
+    });
+    expect(steps[1]).toEqual({
+      key: null,
+      name: 'Checkout',
+      sourceLocation: null,
+      status: 'pending',
+      type: 'checkout',
+      config: {
+        checkout: {
+          repository: 'acme/api',
+          ref: 'refs/heads/main',
+          fetch_depth: 0,
+          path: 'target',
+          permissions: {contents: 'write'},
+          persist_credentials: false,
+          force: true,
+        },
+      },
+      authoredConfig: null,
+      position: 1,
+    });
+  });
+
+  it('places a leading checkout at the job root when its path is omitted', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [{checkout: checkout('acme/api')}, {run: 'echo use checkout'}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({type: 'setup', config: {}});
+    expect(steps[1]).toMatchObject({
+      type: 'checkout',
+      config: {checkout: {repository: 'acme/api', path: '.'}},
+    });
+    expect(steps[2]).toMatchObject({type: 'run', config: {run: 'echo use checkout'}});
+  });
+
+  it('keeps the implicit checkout when an explicit checkout is not leading', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [
+            {run: 'echo route'},
+            {checkout: checkout('acme/api')},
+            {run: 'echo use checkout'},
+          ],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({
+      type: 'setup',
+      config: {
+        checkout: {
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+        },
+      },
+    });
+    expect(steps[2]).toMatchObject({
+      type: 'checkout',
+      config: {
+        checkout: {
+          repository: 'acme/api',
+          fetch_depth: 1,
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+        },
+      },
+    });
+    expect(steps[2]?.config.checkout).not.toHaveProperty('path');
+    expect(steps[3]).toMatchObject({type: 'run', config: {run: 'echo use checkout'}});
+  });
+
+  it('omits the implicit checkout when the job opts out', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          checkout: false,
+          steps: [{run: 'echo no repository'}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({type: 'setup', config: {}});
+  });
+
+  it('does not restore the implicit checkout for a leading checkout with a false if', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [{if: condition('false'), checkout: checkout('acme/api')}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({type: 'setup', config: {}});
+    expect(steps[1]).toMatchObject({
+      type: 'checkout',
+      condition: expect.any(Object),
+      config: {checkout: {repository: 'acme/api', path: '.'}},
+    });
+  });
+
+  it('propagates a non-default job checkout policy into the setup step config', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          checkout: {
+            permissions: {contents: 'write'},
+            persistCredentials: false,
+          },
+          steps: [{run: 'echo hello'}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = await materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps[0]).toMatchObject({
+      type: 'setup',
+      config: {
+        checkout: {
+          permissions: {contents: 'write'},
+          persist_credentials: false,
+        },
+      },
+    });
+  });
+
+  it('falls back to the default checkout policy for legacy jobs', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {steps: [{run: 'echo hello'}]},
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+    const legacyJob = {...job, checkout: undefined} as unknown as typeof job;
+
+    const steps = await materializeJobExecutionSteps({
+      model,
+      job: legacyJob,
+      context: jobExecutionContext(),
+    });
+
+    expect(steps[0]).toMatchObject({
+      type: 'setup',
+      config: {
+        checkout: {
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+        },
+      },
+    });
+  });
+
   it('prepends setup and resolves job-execution context fields', async () => {
     const model = workflowModel({
       jobs: {
@@ -183,7 +427,12 @@ describe('materializeJobExecutionSteps', () => {
         sourceLocation: null,
         status: 'pending',
         type: 'setup',
-        config: {},
+        config: {
+          checkout: {
+            permissions: {contents: 'read'},
+            persist_credentials: true,
+          },
+        },
         authoredConfig: null,
         position: 0,
       },

package/src/core/step-config/materialize-job-execution-steps.ts

@@ -1,4 +1,4 @@
-import type {WorkflowModel} from '@shipfox/api-definitions-dto';
+import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
 import type {WorkflowExpression} from '@shipfox/expression';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import type {
@@ -41,15 +41,14 @@ export interface MaterializeJobExecutionStepsParams {
 
 // Synthetic "Set up job" step prepended when a job execution's steps are materialized.
 // The runner prepares the workspace here; failures report through the normal step
-// protocol instead of hanging the job until the lease/timeout fires. Its config is
-// credential-free.
-const SETUP_STEP: MaterializedWorkflowStep = {
+// protocol instead of hanging the job until the lease/timeout fires. Its config carries
+// checkout policy, never credential material.
+const SETUP_STEP: Omit<MaterializedWorkflowStep, 'config'> = {
   key: null,
   name: 'Set up job',
   sourceLocation: null,
   status: 'pending',
   type: 'setup',
-  config: {},
   authoredConfig: null,
   position: 0,
 };
@@ -68,11 +67,13 @@ export async function materializeJobExecutionSteps(
   } = params;
 
   return [
-    SETUP_STEP,
+    setupStepForJob(job),
     ...(await Promise.all(
       job.steps.map(async (step, stepPosition) => {
-        // The trusted context exposes the stable job key; the authored display field remains `job.name`.
-        const stepContext = {...context.values, job: {key: job.key}};
+        const stepContext = {
+          ...context.values,
+          job: {key: job.key, name: job.name ?? job.key},
+        };
         const resolved = await resolveStepConfig({
           jobKey: job.key,
           step,
@@ -93,7 +94,11 @@ export async function materializeJobExecutionSteps(
           sourceLocation: step.sourceLocation ?? null,
           status: 'pending' as const,
           type: step.kind,
-          config: resolved.config,
+          config: materializedStepConfig({
+            config: resolved.config,
+            step,
+            stepPosition,
+          }),
           ...(step.if === undefined ? {} : {condition: step.if}),
           authoredConfig: resolved.authoredConfig,
           ...materializedConfigPlan(resolved.configPlan, resolved.trace),
@@ -105,6 +110,45 @@ export async function materializeJobExecutionSteps(
   ];
 }
 
+function setupStepForJob(job: WorkflowModelJob): MaterializedWorkflowStep {
+  if (job.checkout === false || job.steps[0]?.kind === 'checkout') {
+    return {...SETUP_STEP, config: {}};
+  }
+
+  const checkout = job.checkout ?? DEFAULT_JOB_CHECKOUT;
+
+  return {
+    ...SETUP_STEP,
+    config: {
+      checkout: {
+        permissions: checkout.permissions,
+        persist_credentials: checkout.persistCredentials,
+      },
+    },
+  };
+}
+
+function materializedStepConfig(params: {
+  readonly config: Readonly<Record<string, unknown>>;
+  readonly step: WorkflowModelStep;
+  readonly stepPosition: number;
+}): Readonly<Record<string, unknown>> {
+  if (
+    params.step.kind !== 'checkout' ||
+    params.stepPosition !== 0 ||
+    params.step.checkout.path !== undefined
+  ) {
+    return params.config;
+  }
+
+  const checkout = params.config.checkout;
+  if (checkout === null || typeof checkout !== 'object' || Array.isArray(checkout)) {
+    throw new Error('Checkout materialization config is missing an object');
+  }
+
+  return {...params.config, checkout: {...checkout, path: '.'}};
+}
+
 function materializedConfigPlan(
   configPlan: StepConfigDispatchPlan | null,
   trace: NonNullable<StepConfigDispatchPlan['trace']>,
@@ -114,13 +158,16 @@ function materializedConfigPlan(
 }
 
 function stepDisplayName(step: WorkflowModelStep): string {
-  switch (step.kind) {
+  const {kind} = step;
+  switch (kind) {
     case 'run':
       return firstLine(step.command.value);
     case 'agent':
       return step.model === undefined
         ? firstLine(step.prompt)
         : `${step.model} · ${firstLine(step.prompt)}`;
+    case 'checkout':
+      return 'Checkout';
     default:
       return assertNever(step);
   }