@shipfox/api-workflows 11.0.0 → 12.0.0

package/src/presentation/routes/checkout-token.ts

@@ -1,20 +1,23 @@
-import {requireLeasedJobContext} from '@shipfox/api-auth-context';
 import {
   type IntegrationsModuleClient,
   integrationsInterModuleContract,
 } from '@shipfox/api-integration-core-dto/inter-module';
-import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import {
+  type ProjectsModuleClient,
+  projectsInterModuleContract,
+} from '@shipfox/api-projects-dto/inter-module';
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
-import {checkoutTokenResponseSchema} from '@shipfox/api-workflows-dto';
+import {
+  checkoutTokenParamsSchema,
+  checkoutTokenQuerySchema,
+  checkoutTokenResponseSchema,
+} from '@shipfox/api-workflows-dto';
 import {isInterModuleKnownError} from '@shipfox/inter-module';
 import {ClientError, defineRoute} from '@shipfox/node-fastify';
-import {createJobCheckoutSpec} from '#core/checkout.js';
-import {
-  CheckoutIntentUnresolvedError,
-  JobNotFoundError,
-  WorkflowRunNotFoundError,
-} from '#core/errors.js';
+import {createStepCheckoutSpec} from '#core/checkout.js';
+import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from '#core/errors.js';
 import {toCheckoutTokenDto} from '#presentation/dto/checkout-token.js';
+import {loadRunningLeasedStep} from './leased-step.js';
 
 export function createCheckoutTokenRoute(clients: {
   runners: RunnersInterModuleClient;
@@ -23,10 +26,14 @@ export function createCheckoutTokenRoute(clients: {
 }) {
   return defineRoute({
     method: 'POST',
-    path: '/checkout-token',
+    path: '/steps/:stepId/checkout-token',
     description:
-      "Exchanges the runner's job lease for short-lived, read-only checkout credentials for the job's repository. The job is identified by the access token, so no job ID is needed. The checkout target is resolved server-side from the job's run and project; no credential material is stored on the job or run. Returns the repository URL, ref, and (when the provider needs auth) a short-lived credential that expires soon.",
-    schema: {response: {200: checkoutTokenResponseSchema}},
+      "Exchanges the runner's lease for short-lived checkout credentials for the currently running checkout step. The step id and attempt are checked against the lease and the server-frozen step config supplies the target, ref, permissions, and fetch depth.",
+    schema: {
+      params: checkoutTokenParamsSchema,
+      querystring: checkoutTokenQuerySchema,
+      response: {200: checkoutTokenResponseSchema},
+    },
     errorHandler: (error) => {
       const known = isInterModuleKnownError(
         integrationsInterModuleContract.methods.createCheckoutSpec,
@@ -34,12 +41,24 @@ export function createCheckoutTokenRoute(clients: {
       )
         ? error
         : undefined;
-      if (error instanceof JobNotFoundError)
-        throw new ClientError(error.message, 'job-not-found', {status: 404});
-      if (error instanceof WorkflowRunNotFoundError)
-        throw new ClientError(error.message, 'run-not-found', {status: 404});
+      const targetError = isInterModuleKnownError(
+        projectsInterModuleContract.methods.resolveCheckoutTarget,
+        error,
+      )
+        ? error
+        : undefined;
       if (error instanceof CheckoutIntentUnresolvedError)
         throw new ClientError(error.message, 'checkout-unavailable', {status: 404});
+      if (error instanceof CheckoutConfigInvalidError)
+        throw new ClientError('Checkout configuration is invalid', 'checkout-config-invalid', {
+          status: 409,
+        });
+      if (targetError?.code === 'checkout-repository-not-authorized')
+        throw new ClientError(
+          'Checkout repository is not authorized for this workspace',
+          'checkout-repository-not-authorized',
+          {status: 404},
+        );
       if (known?.code === 'connection-not-found')
         throw new ClientError(
           'Integration connection not found',
@@ -101,21 +120,32 @@ export function createCheckoutTokenRoute(clients: {
       throw error;
     },
     handler: async (request, reply) => {
-      const leasedJob = requireLeasedJobContext(request);
-      const {active: leaseIsActive} = await clients.runners.getLeaseState({
-        jobId: leasedJob.jobId,
-        jobExecutionId: leasedJob.jobExecutionId,
-        runnerSessionId: leasedJob.runnerSessionId,
+      const {stepId} = request.params;
+      const {attempt} = request.query;
+      const {step, workspaceId, projectId, triggerReference} = await loadRunningLeasedStep({
+        runners: clients.runners,
+        request,
+        stepId,
+        attempt,
       });
-      if (!leaseIsActive)
-        throw new ClientError('Job lease is no longer active', 'lease-not-active', {status: 404});
-      const checkout = await createJobCheckoutSpec({
-        jobId: leasedJob.jobId,
+
+      if (step.type !== 'setup' && step.type !== 'checkout') {
+        throw new ClientError('Step is not a checkout step', 'step-not-checkout', {status: 409});
+      }
+
+      const checkout = await createStepCheckoutSpec({
+        step,
+        workspaceId,
+        projectId,
+        triggerReference,
         integrations: clients.integrations,
         projects: clients.projects,
       });
       reply.header('cache-control', 'no-store');
-      return toCheckoutTokenDto(checkout.spec, {persist: checkout.persistCredentials});
+      return toCheckoutTokenDto(checkout.spec, {
+        fetchDepth: checkout.fetchDepth,
+        persist: checkout.persistCredentials,
+      });
     },
   });
 }

package/src/presentation/routes/get-run.test.ts

@@ -117,6 +117,8 @@ describe('GET /api/workflows/runs/:id', () => {
     expect(res.statusCode).toBe(200);
     const body = res.json();
     expect(body.id).toBe(run.id);
+    expect(body).toMatchObject({name: 'Test', workflow_name: 'Test'});
+    expect(body.number).toBe(run.number);
     expect(body.source_snapshot).toBeNull();
     expect(body.jobs).toHaveLength(1);
     expect(body.jobs[0].key).toBe('build');

package/src/presentation/routes/get-step-secrets.test.ts

@@ -1,5 +1,6 @@
 import {closeApp, createApp, type FastifyInstance} from '@shipfox/node-fastify';
 import {createCapturingLogger} from '@shipfox/node-log/test';
+import {agentThinkingSchema} from '@shipfox/workflow-document';
 import {eq} from 'drizzle-orm';
 import type {StepStatus} from '#core/entities/step.js';
 import {db} from '#db/db.js';
@@ -205,7 +206,11 @@ describe('GET /runs/jobs/current/steps/:stepId/secrets', () => {
 
     const scope = await getJobScope(job.id);
 
-    expect(scope).toEqual({workspaceId: run.workspaceId, projectId: run.projectId});
+    expect(scope).toEqual({
+      workspaceId: run.workspaceId,
+      projectId: run.projectId,
+      triggerReference: null,
+    });
   });
 });
 
@@ -256,7 +261,7 @@ async function createStep(params: {
       harness: defaults.harness ?? 'pi',
       provider: defaults.provider ?? 'anthropic',
       model: defaults.model ?? 'claude-opus-4-8',
-      thinking: defaults.thinking ?? 'high',
+      thinking: agentThinkingSchema.safeParse(defaults.thinking).data ?? 'high',
     }),
     triggerPayload: {
       source: 'manual',

package/src/presentation/routes/leased-step.ts

@@ -2,6 +2,7 @@ import {type LeasedJobContext, requireLeasedJobContext} from '@shipfox/api-auth-
 import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import {ClientError} from '@shipfox/node-fastify';
 import type {Step} from '#core/entities/step.js';
+import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
 import {getJobScope, getStepByIdForJobExecution} from '#db/index.js';
 
 export interface LoadedRunningLeasedStep {
@@ -9,6 +10,7 @@ export interface LoadedRunningLeasedStep {
   step: Step;
   workspaceId: string;
   projectId: string;
+  triggerReference: WorkflowRunTriggerReference | null;
 }
 
 export async function loadRunningLeasedStep(params: {
@@ -51,5 +53,11 @@ export async function loadRunningLeasedStep(params: {
     throw new ClientError('Step is not running', 'step-not-running', {status: 409});
   }
 
-  return {leasedJob, step, workspaceId: scope.workspaceId, projectId: scope.projectId};
+  return {
+    leasedJob,
+    step,
+    workspaceId: scope.workspaceId,
+    projectId: scope.projectId,
+    triggerReference: scope.triggerReference,
+  };
 }

package/src/presentation/routes/list-runs.test.ts

@@ -96,6 +96,7 @@ describe('GET /api/workflows/runs', () => {
     expect(body.runs).toHaveLength(2);
     expect(body.runs[0].project_id).toBe(projectId);
     expect(body.runs[0].name).toBeDefined();
+    expect(body.runs[0].workflow_name).toBeDefined();
     expect(body.runs[0].trigger_source).toBe('manual');
     // The runs list carries run-level timing (null until the run starts).
     expect(body.runs[0]).toMatchObject({started_at: null, finished_at: null});
@@ -103,6 +104,62 @@ describe('GET /api/workflows/runs', () => {
     expect(body.filtered_total_count).toBe(2);
   });
 
+  test('carries the current attempt jobs in graph order so a row can draw its status strip', async () => {
+    await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Pipeline',
+      model: workflowModel({
+        name: 'Pipeline',
+        jobs: {
+          build: {steps: [{run: 'echo build'}]},
+          test: {needs: 'build', steps: [{run: 'echo test'}]},
+          deploy: {needs: 'test', steps: [{run: 'echo deploy'}]},
+        },
+      }),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    const [run] = res.json().runs;
+    expect(run.jobs.map((job: {key: string}) => job.key)).toEqual(['build', 'test', 'deploy']);
+    expect(run.jobs[0]).toMatchObject({status: 'pending', position: 0});
+  });
+
+  test('reports a null trigger reference for a run no source-control event produced', async () => {
+    await createWorkflowRun({
+      workspaceId,
+      projectId,
+      definitionId: crypto.randomUUID(),
+      name: 'Manual',
+      model: workflowModel({name: 'Manual'}),
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: crypto.randomUUID(),
+        userId: crypto.randomUUID(),
+      },
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/api/workflows/runs?project_id=${projectId}`,
+    });
+
+    expect(res.json().runs[0].trigger_reference).toBeNull();
+  });
+
   test('returns empty array for project with no runs', async () => {
     const res = await app.inject({
       method: 'GET',

package/src/presentation/routes/list-runs.ts

@@ -6,8 +6,8 @@ import {
 import {decodeTimestampIdCursor, encodeTimestampIdCursor} from '@shipfox/node-drizzle';
 import {ClientError, defineRoute} from '@shipfox/node-fastify';
 import {logger} from '@shipfox/node-opentelemetry';
-import {listWorkflowRuns} from '#db/index.js';
-import {toRunDto} from '#presentation/dto/index.js';
+import {listWorkflowRunJobSummaries, listWorkflowRuns} from '#db/index.js';
+import {toRunListItemDto} from '#presentation/dto/index.js';
 import {requireProjectAccess} from './project-access.js';
 
 export function listRunsRoute(projects: ProjectsModuleClient) {
@@ -54,6 +54,11 @@ export function listRunsRoute(projects: ProjectsModuleClient) {
         filters,
         includeTotal: !decodedCursor,
       });
+      // Paired with the attempt this read returned, so a re-run landing mid-request cannot
+      // pair one attempt's metadata with another's jobs.
+      const jobsByRun = await listWorkflowRunJobSummaries(
+        result.runs.map((run) => ({id: run.id, currentAttempt: run.currentAttempt})),
+      );
 
       logger().info(
         {
@@ -71,7 +76,7 @@ export function listRunsRoute(projects: ProjectsModuleClient) {
       );
 
       return {
-        runs: result.runs.map((run) => toRunDto(run)),
+        runs: result.runs.map((run) => toRunListItemDto(run, jobsByRun.get(run.id))),
         next_cursor: result.nextCursor ? encodeTimestampIdCursor(result.nextCursor) : null,
         filtered_total_count: result.filteredTotalCount,
       };

package/src/presentation/routes/report-step.test.ts

@@ -215,6 +215,31 @@ describe('POST /runs/jobs/current/steps/:stepId/report', () => {
     expect(attempt?.exitCode).toBe(0);
   });
 
+  test('persists dedicated checkout details alongside user output', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(1);
+    const token = await mintActiveLeaseToken({jobId});
+    await nextStepForJob(jobId);
+    const checkout = {
+      repository: 'https://github.com/acme/api.git',
+      ref: 'refs/pull/412/head',
+      commit: '9f2c000000000000000000000000000000000000',
+      path: '/runner/workspace/job-1',
+    };
+    const res = await app.inject({
+      method: 'POST',
+      url: reportUrl(steps[0]?.id as string),
+      headers: {authorization: `Bearer ${token}`},
+      payload: reportPayload({
+        status: 'succeeded',
+        output: {artifact: 'dist/app.tgz', checkout: 'user-value'},
+        checkout,
+        exit_code: 0,
+      }),
+    });
+    expect(res.statusCode).toBe(200);
+    const [attempt] = await getStepAttempts(jobId);
+    expect(attempt?.output).toEqual({artifact: 'dist/app.tgz', checkout});
+  });
   test('rejects a failed report without an error', async () => {
     const {jobId, steps} = await arrangeJobWithSteps(1);
     const token = await mintActiveLeaseToken({jobId});

package/src/presentation/routes/report-step.ts

@@ -12,7 +12,7 @@ export function createReportStepRoute(runners: RunnersInterModuleClient) {
     method: 'POST',
     path: '/steps/:stepId/report',
     description:
-      'Reports whether a step succeeded or failed. The job is identified by the access token. Reporting the same step more than once is safe: once a step has finished, later reports for it are ignored. The runner does not call a separate job-completion endpoint — finalization is driven server-side from the recorded step results, and the `cancel` flag tells the runner to stop once the job has finished without full success.',
+      'Reports whether a step succeeded or failed. The job is identified by the access token. Reporting the same step more than once is safe: once a step has finished, later reports for it are ignored. The runner does not call a separate job-completion endpoint: finalization is driven server-side from the recorded step results, and the `cancel` flag tells the runner to stop once the job has finished without full success.',
     schema: {
       params: z.object({stepId: z.string().uuid()}),
       body: reportStepBodySchema,
@@ -45,12 +45,20 @@ export function createReportStepRoute(runners: RunnersInterModuleClient) {
         throw new ClientError('Job lease is no longer active', 'lease-not-active', {status: 404});
       }
 
+      // Checkout is a reserved system field on the report wire contract. Keep
+      // it out of the runner's user output merge until this persistence
+      // boundary, where the system value has explicit precedence.
+      const output =
+        request.body.checkout === undefined
+          ? (request.body.output ?? null)
+          : {...(request.body.output ?? {}), checkout: request.body.checkout};
+
       const outcome = await recordStepResult({
         jobExecutionId: leasedJob.jobExecutionId,
         stepId,
         status: request.body.status,
         error: fromStepErrorDto(request.body.error),
-        output: request.body.output ?? null,
+        output,
         response: request.body.response ?? null,
         exitCode: request.body.exit_code ?? request.body.error?.exit_code ?? null,
         logOutcome: request.body.log_outcome,

package/src/presentation/subscribers/on-job-steps-settled.ts

@@ -7,7 +7,7 @@ import {isWorkflowNotFound} from '#temporal/workflow-not-found.js';
 // Per-step execution finishes a job inside recordStepResult (no runner /complete
 // call), which enqueues WORKFLOWS_JOB_STEPS_SETTLED in the same transaction. The
 // persisted per-step projection is already terminal, so the workflow only flips
-// the job status — no steps are carried.
+// the job status: no steps are carried.
 export async function onJobStepsSettled(payload: WorkflowsJobStepsSettledEventDto): Promise<void> {
   logger().info(
     {

package/src/presentation/subscribers/on-runner-job-claimed.test.ts

@@ -2,7 +2,20 @@ import {getJobExecutionsByJobId, getJobsByWorkflowRunId} from '#db/index.js';
 import {workflowRunFactory} from '#test/index.js';
 import {onRunnerJobClaimed} from './on-runner-job-claimed.js';
 
+const signalMock = vi.fn();
+const getHandleMock = vi.fn(() => ({signal: signalMock}));
+
+vi.mock('@shipfox/node-temporal', () => ({
+  temporalClient: () => ({workflow: {getHandle: getHandleMock}}),
+}));
+
 describe('onRunnerJobClaimed', () => {
+  beforeEach(() => {
+    getHandleMock.mockClear();
+    signalMock.mockReset();
+    signalMock.mockResolvedValue(undefined);
+  });
+
   it('stamps started_at on the job execution from the claim event payload', async () => {
     const run = await workflowRunFactory.create();
     const job = (await getJobsByWorkflowRunId(run.id))[0];
@@ -23,6 +36,11 @@ describe('onRunnerJobClaimed', () => {
 
     const after = (await getJobExecutionsByJobId(job.id))[0];
     expect(after?.startedAt?.getTime()).toBe(claimedAt.getTime());
+    expect(getHandleMock).toHaveBeenCalledWith(`job:${job.id}`);
+    expect(signalMock).toHaveBeenCalledWith('job-claimed', {
+      jobExecutionId: jobExecution.id,
+      claimedAt: claimedAt.toISOString(),
+    });
   });
 
   it('is idempotent: a redelivered event keeps the first started_at (coalesce)', async () => {
@@ -54,4 +72,35 @@ describe('onRunnerJobClaimed', () => {
     const after = (await getJobExecutionsByJobId(job.id))[0];
     expect(after?.startedAt?.getTime()).toBe(first.getTime());
   });
+
+  it('discards a claim signal when the job workflow already terminated', async () => {
+    const notFound = new Error('gone');
+    notFound.name = 'WorkflowNotFoundError';
+    signalMock.mockRejectedValueOnce(notFound);
+
+    await expect(
+      onRunnerJobClaimed({
+        workflowRunId: crypto.randomUUID(),
+        workflowRunAttemptId: crypto.randomUUID(),
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        claimedAt: '2026-06-22T10:05:00.000Z',
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('rethrows a transient Temporal signal failure for subscriber retry', async () => {
+    const failure = new Error('temporal unavailable');
+    signalMock.mockRejectedValueOnce(failure);
+
+    await expect(
+      onRunnerJobClaimed({
+        workflowRunId: crypto.randomUUID(),
+        workflowRunAttemptId: crypto.randomUUID(),
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        claimedAt: '2026-06-22T10:05:00.000Z',
+      }),
+    ).rejects.toBe(failure);
+  });
 });

package/src/presentation/subscribers/on-runner-job-claimed.ts

@@ -1,6 +1,9 @@
 import type {RunnerJobClaimedEvent} from '@shipfox/api-runners-dto';
 import {logger} from '@shipfox/node-opentelemetry';
+import {temporalClient} from '@shipfox/node-temporal';
 import {recordJobExecutionStartedAt} from '#db/index.js';
+import {JOB_CLAIMED_SIGNAL} from '#temporal/constants.js';
+import {isWorkflowNotFound} from '#temporal/workflow-not-found.js';
 
 // Anticorruption layer: the runner reports a `claimed` fact in its own lease-broker
 // language; the run lifecycle treats the claim as the job's start, so we project it onto
@@ -20,4 +23,23 @@ export async function onRunnerJobClaimed(payload: RunnerJobClaimedEvent): Promis
     jobExecutionId: payload.jobExecutionId,
     startedAt: new Date(payload.claimedAt),
   });
+
+  const handle = temporalClient().workflow.getHandle(`job:${payload.jobId}`);
+  try {
+    await handle.signal(JOB_CLAIMED_SIGNAL, {
+      jobExecutionId: payload.jobExecutionId,
+      claimedAt: payload.claimedAt,
+    });
+  } catch (err) {
+    // A terminal execution can race the claim outbox delivery. Its persisted status is
+    // authoritative, so discard the signal if Temporal has already closed the workflow.
+    if (isWorkflowNotFound(err)) {
+      logger().debug(
+        {jobId: payload.jobId, jobExecutionId: payload.jobExecutionId},
+        'Job workflow already terminated; claim event discarded',
+      );
+      return;
+    }
+    throw err;
+  }
 }

package/src/temporal/activities/index.ts

@@ -51,6 +51,7 @@ export function createOrchestrationActivities(params: {
       agent: params.agent,
       integrations: params.integrations,
       projects: params.projects,
+      secrets: params.secrets,
     }),
     peekListenerBufferActivity,
     resolveJobListenerActivity,

package/src/temporal/activities/orchestration-activities.ts

@@ -287,6 +287,7 @@ export function createDrainListenerEventsActivity(clients: {
   agent: AgentInterModuleClient;
   integrations?: IntegrationsModuleClient | undefined;
   projects?: ProjectsModuleClient | undefined;
+  secrets: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'>;
 }) {
   return async function drainListenerEventsActivity(params: {
     jobId: string;

package/src/temporal/constants.ts

@@ -2,5 +2,6 @@ export const WORKFLOWS_TASK_QUEUE = 'workflows-orchestrator';
 export const RUN_CANCEL_SIGNAL = 'run-cancel';
 export const JOB_FINISHED_SIGNAL = 'job-finished';
 export const JOB_LEASE_EXPIRED_SIGNAL = 'job-lease-expired';
+export const JOB_CLAIMED_SIGNAL = 'job-claimed';
 export const LISTENER_EVENTS_AVAILABLE_SIGNAL = 'events-available';
 export const LISTENER_RESOLVE_SIGNAL = 'resolve';

package/src/temporal/index.ts

@@ -1,5 +1,6 @@
 export {createOrchestrationActivities} from './activities/index.js';
 export {
+  JOB_CLAIMED_SIGNAL,
   JOB_FINISHED_SIGNAL,
   JOB_LEASE_EXPIRED_SIGNAL,
   WORKFLOWS_TASK_QUEUE,

package/src/temporal/workflows/index.ts

@@ -1,4 +1,5 @@
 export {
+  jobClaimedSignal,
   jobExecutionOrchestration,
   jobFinishedSignal,
   jobLeaseExpiredSignal,