@shipfox/api-workflows 2.0.0

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

@@ -0,0 +1,366 @@
+import {createLeaseTokenAuthMethod, verifyJobLeaseToken} from '@shipfox/api-auth';
+import {closeApp, createApp, type FastifyInstance} from '@shipfox/node-fastify';
+import {eq, sql} from 'drizzle-orm';
+import {JobNotFoundError} from '#core/errors.js';
+import {recordStepResult as recordJobExecutionStepResult} from '#core/job-execution.js';
+import {db} from '#db/db.js';
+import {steps as stepsTable} from '#db/schema/steps.js';
+import {
+  getFirstJobExecutionByJobId,
+  getJobById,
+  getStepsByJobId,
+  getWorkflowRunByAttemptId,
+} from '#db/workflow-runs.js';
+import {insertRunningJobLease, mintActiveLeaseToken} from '#test/fixtures/active-lease-token.js';
+import {arrangeJobWithSteps} from '#test/fixtures/job-with-steps.js';
+import {mintLeaseToken} from '#test/fixtures/lease-token.js';
+import {leaseTokenRouteGroup} from './index.js';
+
+const URL = '/runs/jobs/current/steps/next';
+
+async function recordStepResult(
+  params: Omit<Parameters<typeof recordJobExecutionStepResult>[0], 'jobExecutionId'> & {
+    jobId: string;
+  },
+) {
+  const steps = await getStepsByJobId(params.jobId);
+  const step = steps.find((candidate) => candidate.id === params.stepId);
+  if (!step) throw new JobNotFoundError(params.jobId);
+  const {jobId: _jobId, ...rest} = params;
+  return recordJobExecutionStepResult({...rest, jobExecutionId: step.jobExecutionId});
+}
+
+async function setRunnerToolCapabilities(
+  runnerSessionId: string,
+  capabilities: Record<string, unknown>,
+): Promise<void> {
+  await db().execute(sql`
+    UPDATE runners_runner_sessions
+    SET tool_capabilities = ${JSON.stringify(capabilities)}::jsonb,
+      tool_capabilities_reported_at = now()
+    WHERE id = ${runnerSessionId}
+  `);
+}
+
+async function annotationCount(jobExecutionId: string): Promise<number> {
+  const result = await db().execute<{count: string}>(sql`
+    SELECT count(*)::text AS count
+    FROM annotations_annotations
+    WHERE job_execution_id = ${jobExecutionId}
+  `);
+  return Number(result.rows[0]?.count ?? '0');
+}
+
+describe('POST /runs/jobs/current/steps/next', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createApp({
+      auth: [createLeaseTokenAuthMethod()],
+      routes: [leaseTokenRouteGroup],
+      swagger: false,
+    });
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await closeApp();
+  });
+
+  describe('lease-token auth', () => {
+    test('rejects a request without an Authorization header', async () => {
+      const res = await app.inject({method: 'POST', url: URL});
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects a non-bearer Authorization header', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: 'Token abc'},
+      });
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects a garbage token', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: 'Bearer not-a-token'},
+      });
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects an expired token', async () => {
+      const token = await mintLeaseToken({
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        expiresIn: '-1s',
+      });
+
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: `Bearer ${token}`},
+      });
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects a token signed with the wrong secret', async () => {
+      const token = await mintLeaseToken({
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        secret: 'wrong-secret',
+      });
+
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: `Bearer ${token}`},
+      });
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+
+    test('rejects a token with the wrong audience (e.g. a user JWT)', async () => {
+      const token = await mintLeaseToken({
+        jobId: crypto.randomUUID(),
+        jobExecutionId: crypto.randomUUID(),
+        audience: 'user-session',
+      });
+
+      const res = await app.inject({
+        method: 'POST',
+        url: URL,
+        headers: {authorization: `Bearer ${token}`},
+      });
+
+      expect(res.statusCode).toBe(401);
+      expect(res.json().code).toBe('unauthorized');
+    });
+  });
+
+  test('returns the lowest-position pending step and marks it running', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(3);
+    const token = await mintActiveLeaseToken({jobId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.kind).toBe('step');
+    expect(body.step.id).toBe(steps[0]?.id);
+    expect(body.step.status).toBe('running');
+    expect(body.lease_token).toEqual(expect.any(String));
+    const scopedLease = await verifyJobLeaseToken(body.lease_token);
+    expect(scopedLease).toMatchObject({
+      jobId,
+      jobExecutionId: steps[0]?.jobExecutionId,
+      currentStepId: steps[0]?.id,
+      currentStepAttempt: 1,
+    });
+    const after = await getStepsByJobId(jobId);
+    expect(after[0]?.status).toBe('running');
+    expect(after[1]?.status).toBe('pending');
+  });
+
+  test('re-delivers the in-flight step on a retried pull', async () => {
+    const {jobId} = await arrangeJobWithSteps(3);
+    const token = await mintActiveLeaseToken({jobId});
+    const first = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    const second = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(second.statusCode).toBe(200);
+    expect(second.json().step.id).toBe(first.json().step.id);
+    const running = (await getStepsByJobId(jobId)).filter((s) => s.status === 'running');
+    expect(running).toHaveLength(1);
+  });
+
+  test('writes the tool capability warning only on fresh dispatch', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(1);
+    await db()
+      .update(stepsTable)
+      .set({
+        type: 'agent',
+        config: {
+          harness: 'pi',
+          provider: 'anthropic',
+          model: 'claude-opus-4-8',
+          thinking: 'high',
+          tools: ['read', 'web_search'],
+          prompt: 'Fix it.',
+        },
+      })
+      .where(eq(stepsTable.id, steps[0]?.id as string));
+    const token = await mintActiveLeaseToken({jobId});
+    const lease = await verifyJobLeaseToken(token);
+    if (!lease) throw new Error('Expected minted lease token to verify');
+    await setRunnerToolCapabilities(lease.runnerSessionId, {harnesses: {pi: {tools: ['read']}}});
+
+    const first = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+    const second = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(first.statusCode).toBe(200);
+    expect(second.statusCode).toBe(200);
+    expect(await annotationCount(lease.jobExecutionId)).toBe(1);
+  });
+
+  test('returns 404 for a valid token without an active lease', async () => {
+    const token = await mintLeaseToken({
+      jobId: crypto.randomUUID(),
+      jobExecutionId: crypto.randomUUID(),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('lease-not-active');
+  });
+
+  test('returns 404 when the lease token is no longer the active job lease', async () => {
+    const {jobId} = await arrangeJobWithSteps(1);
+    const jobExecution = await getFirstJobExecutionByJobId(jobId);
+    if (!jobExecution) throw new Error('Expected job execution to exist');
+    const job = await getJobById(jobId);
+    if (!job) throw new Error('Expected job to exist');
+    const run = await getWorkflowRunByAttemptId(job.workflowRunAttemptId);
+    if (!run) throw new Error('Expected workflow run to exist');
+    await insertRunningJobLease({
+      workspaceId: run.workspaceId,
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      jobId,
+      jobExecutionId: jobExecution.id,
+      projectId: run.projectId,
+      runnerSessionId: crypto.randomUUID(),
+    });
+    const token = await mintLeaseToken({
+      jobId,
+      jobExecutionId: jobExecution.id,
+      workflowRunId: run.id,
+      workflowRunAttemptId: job.workflowRunAttemptId,
+      projectId: run.projectId,
+      workspaceId: run.workspaceId,
+      runnerSessionId: crypto.randomUUID(),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('lease-not-active');
+  });
+
+  test('reports {done, succeeded} once every step succeeded', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(2);
+    const token = await mintActiveLeaseToken({jobId});
+    for (const step of steps) {
+      await app.inject({method: 'POST', url: URL, headers: {authorization: `Bearer ${token}`}});
+      await recordStepResult({jobId, stepId: step.id, status: 'succeeded'});
+    }
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({kind: 'done', status: 'succeeded'});
+  });
+
+  test('reports {done, failed} after a failed step skips the default-gated rest', async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(2);
+    const token = await mintActiveLeaseToken({jobId});
+    await app.inject({method: 'POST', url: URL, headers: {authorization: `Bearer ${token}`}});
+    await recordStepResult({jobId, stepId: steps[0]?.id as string, status: 'failed'});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({kind: 'done', status: 'failed'});
+  });
+
+  test('concurrent pulls hand out the same step exactly once', async () => {
+    const {jobId} = await arrangeJobWithSteps(3);
+    const token = await mintActiveLeaseToken({jobId});
+
+    const responses = await Promise.all(
+      Array.from({length: 5}, () =>
+        app.inject({method: 'POST', url: URL, headers: {authorization: `Bearer ${token}`}}),
+      ),
+    );
+
+    const ids = responses.map((res) => {
+      expect(res.statusCode).toBe(200);
+      return res.json().step.id;
+    });
+    expect(new Set(ids).size).toBe(1);
+    const running = (await getStepsByJobId(jobId)).filter((s) => s.status === 'running');
+    expect(running).toHaveLength(1);
+  });
+
+  test("returns the step's current attempt so the runner can echo it", async () => {
+    const {jobId, steps} = await arrangeJobWithSteps(2);
+    // Simulate a durable restart having bumped the first step's current attempt.
+    await db()
+      .update(stepsTable)
+      .set({currentAttempt: 2})
+      .where(eq(stepsTable.id, steps[0]?.id as string));
+    const token = await mintActiveLeaseToken({jobId});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: URL,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.attempt).toBe(2);
+    const scopedLease = await verifyJobLeaseToken(body.lease_token);
+    expect(scopedLease?.currentStepId).toBe(steps[0]?.id);
+    expect(scopedLease?.currentStepAttempt).toBe(body.attempt);
+  });
+});

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

@@ -0,0 +1,62 @@
+import {issueJobLeaseToken, jobLeaseParamsFrom} from '@shipfox/api-auth';
+import {requireLeasedJobContext} from '@shipfox/api-auth-context';
+import {nextStepResponseSchema} from '@shipfox/api-workflows-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {warnAgentToolCapabilityMismatchOnDispatch} from '#core/agent-tool-capability-warning.js';
+import {JobLeaseNotActiveError, JobNotFoundError} from '#core/errors.js';
+import {nextStepForLeasedJobExecution} from '#core/job-execution.js';
+import {toStepDto} from '#presentation/dto/step.js';
+
+export const nextStepRoute = defineRoute({
+  method: 'POST',
+  path: '/steps/next',
+  description:
+    'Returns the next step for the runner to run on its job. The job is identified by the access token, so no job ID is needed. Calling this again before reporting the current step returns that same step, so retries are safe. When no runnable steps remain, the response reports that there are no more steps to run, along with the job status; the runner then stops. Finalization is driven server-side from recorded step results and dispatch-time skips, not by the runner calling a job-completion endpoint.',
+  schema: {
+    response: {
+      200: nextStepResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof JobNotFoundError) {
+      throw new ClientError(error.message, 'job-not-found', {status: 404});
+    }
+    if (error instanceof JobLeaseNotActiveError) {
+      throw new ClientError('Job lease is no longer active', 'lease-not-active', {status: 404});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const leasedJob = requireLeasedJobContext(request);
+
+    const next = await nextStepForLeasedJobExecution({
+      jobId: leasedJob.jobId,
+      jobExecutionId: leasedJob.jobExecutionId,
+      runnerSessionId: leasedJob.runnerSessionId,
+    });
+
+    if (next.kind === 'step') {
+      const leaseToken = await issueJobLeaseToken(
+        jobLeaseParamsFrom(leasedJob, {
+          currentStepId: next.step.id,
+          currentStepAttempt: next.step.currentAttempt,
+        }),
+      );
+      if (next.dispatched) {
+        await warnAgentToolCapabilityMismatchOnDispatch({
+          leaseIdentity: leasedJob,
+          step: next.step,
+        });
+      }
+      // The runner echoes this back on report so a stale report from a superseded
+      // attempt is ignored.
+      return {
+        kind: 'step' as const,
+        step: toStepDto(next.step),
+        attempt: next.step.currentAttempt,
+        lease_token: leaseToken,
+      };
+    }
+    return {kind: 'done' as const, status: next.status};
+  },
+});