@shipfox/api-workflows 16.1.0 → 17.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "16.1.0",
+  "version": "17.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,30 +23,30 @@
     "drizzle-orm": "^0.45.2",
     "js-yaml": "^4.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "15.0.0",
-    "@shipfox/api-auth-dto": "15.0.0",
-    "@shipfox/api-agent-dto": "16.1.0",
+    "@shipfox/api-auth-context": "17.0.0",
+    "@shipfox/api-auth-dto": "17.0.0",
+    "@shipfox/api-agent-dto": "17.1.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-definitions-dto": "16.1.0",
+    "@shipfox/api-definitions-dto": "17.0.0",
     "@shipfox/api-projects-dto": "15.0.0",
     "@shipfox/api-integration-core-dto": "16.0.0",
     "@shipfox/api-runners-dto": "16.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "16.1.0",
+    "@shipfox/api-workflows-dto": "17.1.0",
     "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.4.0",
+    "@shipfox/expression": "2.4.1",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-fastify": "0.4.3",
     "@shipfox/node-module": "1.0.7",
     "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/node-postgres": "0.5.0",
+    "@shipfox/node-postgres": "0.5.1",
     "@shipfox/node-temporal": "0.4.6",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.3.0"
+    "@shipfox/workflow-document": "3.3.1"
   },
   "imports": {
     "#*": "./dist/*"

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

@@ -21,6 +21,7 @@ import {
 const mocks = vi.hoisted(() => ({
   deliverEventToListener: vi.fn(),
   getJobScope: vi.fn(),
+  getStepAttemptDetail: vi.fn(),
   getStepById: vi.fn(),
   getStepByIdForJobExecution: vi.fn(),
   listStepAttemptIdsByJobId: vi.fn(),
@@ -49,6 +50,7 @@ describe('Workflows inter-module presentation', () => {
   beforeEach(() => {
     mocks.getJobScope.mockReset();
     mocks.listStepAttemptIdsByJobId.mockReset();
+    mocks.getStepAttemptDetail.mockReset();
     mocks.getStepById.mockReset();
     mocks.getStepByIdForJobExecution.mockReset();
     mocks.deliverEventToListener.mockReset();
@@ -162,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,
@@ -34,6 +38,7 @@ import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-referenc
 import {assertWorkspaceAdmitsNewJobs} from '#core/workspace-admission.js';
 import {
   getJobScope,
+  getStepAttemptDetail,
   getStepById,
   getStepByIdForJobExecution,
   listStepAttemptIdsByJobId,
@@ -53,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 {
@@ -161,28 +225,7 @@ export function createWorkflowsInterModulePresentation(params: {
     },
     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) {
@@ -190,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,
+      };
+    },
   });
 }