@shipfox/api-workflows 16.0.0 → 17.0.0

package/src/presentation/inter-module.test.ts

@@ -21,8 +21,10 @@ import {
 const mocks = vi.hoisted(() => ({
   deliverEventToListener: vi.fn(),
   getJobScope: vi.fn(),
+  getStepAttemptDetail: vi.fn(),
   getStepById: vi.fn(),
   getStepByIdForJobExecution: vi.fn(),
+  listStepAttemptIdsByJobId: vi.fn(),
 }));
 
 vi.mock('#db/index.js', () => mocks);
@@ -47,12 +49,38 @@ const input = {
 describe('Workflows inter-module presentation', () => {
   beforeEach(() => {
     mocks.getJobScope.mockReset();
+    mocks.listStepAttemptIdsByJobId.mockReset();
+    mocks.getStepAttemptDetail.mockReset();
     mocks.getStepById.mockReset();
     mocks.getStepByIdForJobExecution.mockReset();
     mocks.deliverEventToListener.mockReset();
     mocks.deliverEventToListener.mockResolvedValue({buffered: true, skipped: false});
   });
 
+  it('returns the step attempt ids of a job for the session release sweep', async () => {
+    const stepAttemptId = '00000000-0000-4000-8000-000000000010';
+    mocks.listStepAttemptIdsByJobId.mockResolvedValue([stepAttemptId]);
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {getWorkspaceOperatingState: vi.fn()} as never,
+    });
+
+    const result = await presentation.handlers.listJobStepAttempts(
+      {jobId: '00000000-0000-4000-8000-000000000006'},
+      {signal: new AbortController().signal},
+    );
+
+    expect(mocks.listStepAttemptIdsByJobId).toHaveBeenCalledWith(
+      '00000000-0000-4000-8000-000000000006',
+    );
+    expect(result).toEqual({stepAttemptIds: [stepAttemptId]});
+  });
+
   it('returns only the resolved harness for Logs', async () => {
     mocks.getStepById.mockResolvedValue({config: {harness: 'claude'}});
     const presentation = createWorkflowsInterModulePresentation({
@@ -136,6 +164,201 @@ describe('Workflows inter-module presentation', () => {
     });
   });
 
+  describe('getLeasedAgentSessionContext', () => {
+    const input = {
+      jobId: '00000000-0000-4000-8000-000000000006',
+      jobExecutionId: '00000000-0000-4000-8000-000000000007',
+      runnerSessionId: '00000000-0000-4000-8000-000000000008',
+      stepId: '00000000-0000-4000-8000-000000000009',
+      attempt: 1,
+    };
+
+    const method = workflowsInterModuleContract.methods.getLeasedAgentSessionContext;
+
+    function presentation(runners: {getLeaseState: ReturnType<typeof vi.fn>}) {
+      return createWorkflowsInterModulePresentation({
+        agent: {} as never,
+        definitions: {} as never,
+        integrations: {} as never,
+        projects: {} as never,
+        runners: runners as never,
+        secrets: {} as never,
+        workspaces: {getWorkspaceOperatingState: vi.fn()} as never,
+      });
+    }
+
+    async function expectKnownError(call: Promise<unknown> | unknown, code: string): Promise<void> {
+      try {
+        await call;
+        throw new Error(`Expected contract error ${code}, but the call succeeded`);
+      } catch (error) {
+        expect(isInterModuleKnownError(method, error) && (error as {code: string}).code).toBe(code);
+      }
+    }
+
+    function arrangeRunningAgentStep() {
+      mocks.getStepByIdForJobExecution.mockResolvedValue({
+        currentAttempt: input.attempt,
+        status: 'running',
+        type: 'agent',
+        config: {},
+      });
+      mocks.getJobScope.mockResolvedValue({
+        workspaceId: '00000000-0000-4000-8000-000000000010',
+        projectId: '00000000-0000-4000-8000-000000000011',
+      });
+    }
+
+    it('returns the recorded session descriptor with the resolved scope', async () => {
+      const stepAttemptId = '00000000-0000-4000-8000-000000000012';
+      const sessionId = '00000000-0000-4000-8000-000000000013';
+      arrangeRunningAgentStep();
+      mocks.getStepAttemptDetail.mockResolvedValue({
+        workflowRunId: '00000000-0000-4000-8000-000000000014',
+        workflowRunAttemptId: '00000000-0000-4000-8000-000000000015',
+        step: {},
+        attempt: {
+          id: stepAttemptId,
+          config: {
+            session: {id: sessionId, key: 'main', mode: 'resume', segment: 3},
+          },
+        },
+      });
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+
+      const result = await presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+        signal: new AbortController().signal,
+      });
+
+      expect(result).toEqual({
+        workspaceId: '00000000-0000-4000-8000-000000000010',
+        projectId: '00000000-0000-4000-8000-000000000011',
+        workflowRunAttemptId: '00000000-0000-4000-8000-000000000015',
+        stepAttemptId,
+        session: {id: sessionId, key: 'main', mode: 'resume', segment: 3},
+      });
+      expect(mocks.getStepAttemptDetail).toHaveBeenCalledWith({
+        stepId: input.stepId,
+        attempt: input.attempt,
+      });
+    });
+
+    it('returns a null session when the step has no recorded descriptor', async () => {
+      arrangeRunningAgentStep();
+      mocks.getStepAttemptDetail.mockResolvedValue({
+        workflowRunId: '00000000-0000-4000-8000-000000000014',
+        workflowRunAttemptId: '00000000-0000-4000-8000-000000000015',
+        step: {},
+        attempt: {id: '00000000-0000-4000-8000-000000000012', config: null},
+      });
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+
+      const result = await presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+        signal: new AbortController().signal,
+      });
+
+      expect(result.session).toBeNull();
+    });
+
+    it('fails fast when the lease is not active', async () => {
+      arrangeRunningAgentStep();
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: false})};
+
+      await expectKnownError(
+        presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+          signal: new AbortController().signal,
+        }),
+        'lease-not-active',
+      );
+      expect(mocks.getStepAttemptDetail).not.toHaveBeenCalled();
+    });
+
+    it('rejects a malformed recorded descriptor', async () => {
+      arrangeRunningAgentStep();
+      mocks.getStepAttemptDetail.mockResolvedValue({
+        workflowRunId: '00000000-0000-4000-8000-000000000014',
+        workflowRunAttemptId: '00000000-0000-4000-8000-000000000015',
+        step: {},
+        attempt: {
+          id: '00000000-0000-4000-8000-000000000012',
+          config: {session: {id: 'not-a-uuid', key: 'main', mode: 'resume', segment: 1}},
+        },
+      });
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+
+      await expectKnownError(
+        presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+          signal: new AbortController().signal,
+        }),
+        'step-session-config-invalid',
+      );
+    });
+
+    test.each([
+      ['step-not-found', undefined],
+      ['step-attempt-mismatch', {currentAttempt: 2, status: 'running', type: 'agent'}],
+      ['step-not-running', {currentAttempt: 1, status: 'succeeded', type: 'agent'}],
+      ['leased-step-not-agent', {currentAttempt: 1, status: 'running', type: 'run'}],
+    ] as const)('maps a %s step to the published contract error', async (code, step) => {
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+      mocks.getStepByIdForJobExecution.mockResolvedValue(step);
+      if (step !== undefined) {
+        mocks.getJobScope.mockResolvedValue({
+          workspaceId: '00000000-0000-4000-8000-000000000010',
+          projectId: '00000000-0000-4000-8000-000000000011',
+        });
+      }
+
+      await expectKnownError(
+        presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+          signal: new AbortController().signal,
+        }),
+        code,
+      );
+    });
+
+    it('maps a missing job scope to job-not-found', async () => {
+      mocks.getStepByIdForJobExecution.mockResolvedValue({
+        currentAttempt: input.attempt,
+        status: 'running',
+        type: 'agent',
+        config: {},
+      });
+      mocks.getJobScope.mockResolvedValue(undefined);
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+
+      await expectKnownError(
+        presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+          signal: new AbortController().signal,
+        }),
+        'job-not-found',
+      );
+      expect(mocks.getStepAttemptDetail).not.toHaveBeenCalled();
+    });
+
+    it('maps a missing step attempt detail to step-attempt-mismatch', async () => {
+      mocks.getStepByIdForJobExecution.mockResolvedValue({
+        currentAttempt: input.attempt,
+        status: 'running',
+        type: 'agent',
+        config: {},
+      });
+      mocks.getJobScope.mockResolvedValue({
+        workspaceId: '00000000-0000-4000-8000-000000000010',
+        projectId: '00000000-0000-4000-8000-000000000011',
+      });
+      mocks.getStepAttemptDetail.mockResolvedValue(undefined);
+      const runners = {getLeaseState: vi.fn().mockResolvedValue({active: true})};
+
+      await expectKnownError(
+        presentation(runners).handlers.getLeasedAgentSessionContext(input, {
+          signal: new AbortController().signal,
+        }),
+        'step-attempt-mismatch',
+      );
+    });
+  });
+
   test.each([
     ['definition-not-found', () => new DefinitionNotFoundError(input.definitionId)],
     ['project-mismatch', () => new ProjectMismatchError(input.projectId, input.definitionId)],

package/src/presentation/inter-module.ts

@@ -1,4 +1,7 @@
-import {materializedAgentStepConfigSchema} from '@shipfox/api-agent-dto';
+import {
+  agentSessionDescriptorSchema,
+  materializedAgentStepConfigSchema,
+} from '@shipfox/api-agent-dto';
 import type {AgentInterModuleClient} from '@shipfox/api-agent-dto/inter-module';
 import type {DefinitionsInterModuleClient} from '@shipfox/api-definitions-dto/inter-module';
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
@@ -14,6 +17,7 @@ import {
   type InterModulePresentation,
 } from '@shipfox/inter-module';
 import {DEFAULT_HARNESS, harnessSchema} from '@shipfox/workflow-document';
+import type {Step} from '#core/entities/step.js';
 import type {WorkflowRunTriggerReference} from '#core/entities/workflow-run.js';
 import {
   InvalidJobRunnerLabelsError,
@@ -32,7 +36,13 @@ import {
 } from '#core/index.js';
 import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-reference.js';
 import {assertWorkspaceAdmitsNewJobs} from '#core/workspace-admission.js';
-import {getJobScope, getStepById, getStepByIdForJobExecution} from '#db/index.js';
+import {
+  getJobScope,
+  getStepAttemptDetail,
+  getStepById,
+  getStepByIdForJobExecution,
+  listStepAttemptIdsByJobId,
+} from '#db/index.js';
 import {deliverEventToListener} from '#db/job-listener-events.js';
 
 type WorkspaceAdmissionKnownError = InterModuleKnownErrorFor<
@@ -48,6 +58,65 @@ export function createWorkflowsInterModulePresentation(params: {
   integrations: IntegrationsModuleClient;
   projects: ProjectsModuleClient;
 }): InterModulePresentation<typeof workflowsInterModuleContract> {
+  /**
+   * Shared lease + running-agent-step resolution for the lease-authed
+   * inter-module methods (`getLeasedAgentToolContext` and
+   * `getLeasedAgentSessionContext`): verifies the runner lease, resolves the
+   * step for the job execution, then validates the job scope, attempt, status,
+   * and agent type in one canonical order. The two seams previously
+   * copy-pasted this chain with diverging check orders (the tool method
+   * resolved the job scope before the attempt/status checks, the session
+   * method after), so the same underlying state surfaced different errors
+   * depending on the method; a single helper keeps error codes and check
+   * ordering from drifting.
+   *
+   * `loadRunningLeasedStep` (routes) deliberately keeps its own copy: it
+   * returns the run scope (trigger reference/origin state), skips the
+   * agent-type check, and speaks HTTP `ClientError`s instead of contract
+   * known errors.
+   */
+  async function resolveLeasedAgentStep(resolution: {
+    method:
+      | typeof workflowsInterModuleContract.methods.getLeasedAgentToolContext
+      | typeof workflowsInterModuleContract.methods.getLeasedAgentSessionContext;
+    input: {
+      jobId: string;
+      jobExecutionId: string;
+      runnerSessionId: string;
+      stepId: string;
+      attempt: number;
+    };
+  }): Promise<{
+    step: Step;
+    scope: NonNullable<Awaited<ReturnType<typeof getJobScope>>>;
+  }> {
+    const {active: leaseIsActive} = await params.runners.getLeaseState({
+      jobId: resolution.input.jobId,
+      jobExecutionId: resolution.input.jobExecutionId,
+      runnerSessionId: resolution.input.runnerSessionId,
+    });
+    if (!leaseIsActive)
+      throw createInterModuleKnownError(resolution.method, 'lease-not-active', {});
+
+    const step = await getStepByIdForJobExecution({
+      stepId: resolution.input.stepId,
+      jobExecutionId: resolution.input.jobExecutionId,
+    });
+    if (!step) throw createInterModuleKnownError(resolution.method, 'step-not-found', {});
+
+    const scope = await getJobScope(resolution.input.jobId);
+    if (!scope) throw createInterModuleKnownError(resolution.method, 'job-not-found', {});
+    if (step.currentAttempt !== resolution.input.attempt) {
+      throw createInterModuleKnownError(resolution.method, 'step-attempt-mismatch', {});
+    }
+    if (step.status !== 'running')
+      throw createInterModuleKnownError(resolution.method, 'step-not-running', {});
+    if (step.type !== 'agent')
+      throw createInterModuleKnownError(resolution.method, 'leased-step-not-agent', {});
+
+    return {step, scope};
+  }
+
   return defineInterModulePresentation(workflowsInterModuleContract, {
     startRunFromTrigger: async (input) => {
       try {
@@ -151,30 +220,12 @@ export function createWorkflowsInterModulePresentation(params: {
       const parsed = harnessSchema.safeParse(step?.config.harness);
       return {harness: parsed.success ? parsed.data : DEFAULT_HARNESS};
     },
+    listJobStepAttempts: async ({jobId}) => {
+      return {stepAttemptIds: await listStepAttemptIdsByJobId(jobId)};
+    },
     getLeasedAgentToolContext: async (input) => {
       const method = workflowsInterModuleContract.methods.getLeasedAgentToolContext;
-      const {active: leaseIsActive} = await params.runners.getLeaseState({
-        jobId: input.jobId,
-        jobExecutionId: input.jobExecutionId,
-        runnerSessionId: input.runnerSessionId,
-      });
-      if (!leaseIsActive) throw createInterModuleKnownError(method, 'lease-not-active', {});
-
-      const step = await getStepByIdForJobExecution({
-        stepId: input.stepId,
-        jobExecutionId: input.jobExecutionId,
-      });
-      if (!step) throw createInterModuleKnownError(method, 'step-not-found', {});
-
-      const scope = await getJobScope(input.jobId);
-      if (!scope) throw createInterModuleKnownError(method, 'job-not-found', {});
-      if (step.currentAttempt !== input.attempt) {
-        throw createInterModuleKnownError(method, 'step-attempt-mismatch', {});
-      }
-      if (step.status !== 'running')
-        throw createInterModuleKnownError(method, 'step-not-running', {});
-      if (step.type !== 'agent')
-        throw createInterModuleKnownError(method, 'leased-step-not-agent', {});
+      const {step, scope} = await resolveLeasedAgentStep({method, input});
 
       const config = materializedAgentStepConfigSchema.safeParse(step.config);
       if (!config.success) {
@@ -182,6 +233,37 @@ export function createWorkflowsInterModulePresentation(params: {
       }
       return {workspaceId: scope.workspaceId, integrations: config.data.integrations ?? []};
     },
+    getLeasedAgentSessionContext: async (input) => {
+      const method = workflowsInterModuleContract.methods.getLeasedAgentSessionContext;
+      const {scope} = await resolveLeasedAgentStep({method, input});
+
+      const detail = await getStepAttemptDetail({stepId: input.stepId, attempt: input.attempt});
+      if (!detail) throw createInterModuleKnownError(method, 'step-attempt-mismatch', {});
+
+      // The dispatch integration records the resolved descriptor on the step
+      // attempt's config; anything else is a recording we cannot trust.
+      const recorded = detail.attempt.config?.session;
+      if (recorded === undefined || recorded === null) {
+        return {
+          workspaceId: scope.workspaceId,
+          projectId: scope.projectId,
+          workflowRunAttemptId: detail.workflowRunAttemptId,
+          stepAttemptId: detail.attempt.id,
+          session: null,
+        };
+      }
+      const parsed = agentSessionDescriptorSchema.safeParse(recorded);
+      if (!parsed.success) {
+        throw createInterModuleKnownError(method, 'step-session-config-invalid', {});
+      }
+      return {
+        workspaceId: scope.workspaceId,
+        projectId: scope.projectId,
+        workflowRunAttemptId: detail.workflowRunAttemptId,
+        stepAttemptId: detail.attempt.id,
+        session: parsed.data,
+      };
+    },
   });
 }
 

package/src/presentation/routes/agent-runtime-config.test.ts

@@ -54,6 +54,8 @@ const agentTestClient: AgentInterModuleClient = {
   getValidationCatalog: vi.fn(),
   resolveAgentConfig: vi.fn(),
   resolveRuntimeCredentials,
+  claimSession: vi.fn(),
+  carryOverSessions: vi.fn(),
 };
 
 describe('GET /runs/jobs/current/agent-runtime-config', () => {

package/test/factories/workflow-model.ts

@@ -1,4 +1,9 @@
-import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
+import {
+  DEFAULT_JOB_CHECKOUT,
+  type WorkflowJsonTemplateTree,
+  type WorkflowJsonValue,
+  type WorkflowModel,
+} from '@shipfox/api-definitions-dto';
 import {
   createWorkflowExpression,
   parseWorkflowTemplate,
@@ -41,7 +46,14 @@ interface TestCheckoutStep extends TestWorkflowStepBase {
   readonly checkout: Checkout;
 }
 
-type TestWorkflowStep = TestRunStep | TestAgentStep | TestCheckoutStep;
+interface TestToolStep extends TestWorkflowStepBase {
+  readonly tool: string;
+  readonly connection?: string | undefined;
+  readonly with?: WorkflowJsonValue | undefined;
+  readonly outputs?: Readonly<Record<string, string>> | undefined;
+}
+
+type TestWorkflowStep = TestRunStep | TestAgentStep | TestCheckoutStep | TestToolStep;
 
 const DEFAULT_RUNNER_LABELS = ['ubuntu-latest'] as const;
 
@@ -171,6 +183,18 @@ function normalizeStep(step: TestWorkflowStep, jobId: string, stepIndex: number)
     };
   }
 
+  if ('tool' in step) {
+    return {
+      ...base,
+      kind: 'tool',
+      tool: splitToolId(step.tool),
+      ...(step.connection === undefined ? {} : {connection: step.connection}),
+      ...(step.with === undefined ? {} : {with: step.with}),
+      ...(step.outputs === undefined ? {} : {outputMappings: outputMappings(step.outputs)}),
+      ...optionalToolTemplates(step),
+    };
+  }
+
   return {
     ...base,
     kind: 'checkout',
@@ -274,6 +298,54 @@ function optionalAgentTemplates(step: TestAgentStep) {
   };
 }
 
+function optionalToolTemplates(step: TestToolStep) {
+  const withTree = step.with === undefined ? undefined : withTemplateTree(step.with);
+  const name = step.name === undefined ? undefined : fieldTemplate('step.name', step.name);
+  if (withTree === undefined && name === undefined) return {};
+  return {
+    templates: {
+      ...(withTree === undefined ? {} : {with: withTree}),
+      ...(name === undefined ? {} : {name}),
+    },
+  };
+}
+
+function withTemplateTree(value: WorkflowJsonValue): WorkflowJsonTemplateTree | undefined {
+  if (Array.isArray(value)) {
+    const trees = value.map((child) => withTemplateTree(child));
+    return trees.every((tree) => tree === undefined) ? undefined : trees;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value).flatMap(([key, child]) => {
+      const tree = withTemplateTree(child);
+      return tree === undefined ? [] : [[key, tree] as const];
+    });
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+  }
+  if (typeof value !== 'string') return undefined;
+  return fieldTemplate('tool.with', value);
+}
+
+function outputMappings(outputs: Readonly<Record<string, string>>) {
+  return Object.fromEntries(
+    Object.entries(outputs).map(([key, source]) => {
+      const template = fieldTemplate('tool.outputs', source);
+      if (template === undefined || template.length !== 1 || template[0]?.kind !== 'deferred') {
+        throw new Error(
+          `Expected test tool output mapping to be exactly one expression for ${key}: ${source}`,
+        );
+      }
+      return [key, template[0].expression];
+    }),
+  );
+}
+
+function splitToolId(source: string): {readonly id: string; readonly method?: string} {
+  const dotIndex = source.indexOf('.');
+  if (dotIndex < 1 || dotIndex === source.length - 1) return {id: source};
+  return {id: source.slice(0, dotIndex), method: source.slice(dotIndex + 1)};
+}
+
 function envTemplates(env: WorkflowModel['env'] | undefined): WorkflowEnvTemplates | undefined {
   if (env === undefined) return undefined;
 

package/test/fixtures/agent-inter-module.ts

@@ -46,6 +46,8 @@ export const agentTestClient: AgentInterModuleClient = {
       credentials: {api_key: 'test-agent-credential'},
     });
   },
+  claimSession: vi.fn(),
+  carryOverSessions: vi.fn(),
 };
 
 export const resolveTestAgentDefaults: AgentDefaultsResolver = (config) => {