@shipfox/api-integration-core 5.0.0 → 7.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "7.0.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -27,26 +27,29 @@
     "ajv": "^8.20.0",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "5.0.0",
-    "@shipfox/api-auth-context": "5.0.0",
-    "@shipfox/api-integration-core-dto": "5.0.0",
-    "@shipfox/api-integration-gitea": "5.0.0",
-    "@shipfox/api-integration-github": "5.0.0",
-    "@shipfox/api-integration-jira": "5.0.0",
-    "@shipfox/api-integration-linear": "5.0.0",
-    "@shipfox/api-integration-sentry": "5.0.0",
-    "@shipfox/api-integration-slack": "5.0.0",
-    "@shipfox/api-integration-webhook": "5.0.0",
+    "@shipfox/api-agent-dto": "6.0.0",
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-workflows-dto": "6.0.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-workspaces-dto": "6.0.0",
+    "@shipfox/api-integration-gitea": "6.0.0",
+    "@shipfox/api-integration-github": "7.0.1",
+    "@shipfox/api-integration-jira": "7.0.1",
+    "@shipfox/api-integration-linear": "7.0.1",
+    "@shipfox/api-integration-sentry": "6.0.0",
+    "@shipfox/api-integration-slack": "6.0.0",
+    "@shipfox/api-integration-webhook": "6.0.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-drizzle": "0.3.1",
-    "@shipfox/node-fastify": "0.2.3",
-    "@shipfox/node-module": "0.3.2",
+    "@shipfox/inter-module": "0.2.0",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-module": "0.4.0",
     "@shipfox/node-opentelemetry": "0.5.2",
-    "@shipfox/node-outbox": "0.2.3",
+    "@shipfox/node-outbox": "0.2.4",
     "@shipfox/node-postgres": "0.4.2",
-    "@shipfox/node-temporal": "0.3.1",
+    "@shipfox/node-temporal": "0.3.2",
     "@shipfox/regex": "0.2.2",
-    "@shipfox/redact": "0.2.2"
+    "@shipfox/redact": "0.2.3"
   },
   "devDependencies": {
     "@temporalio/activity": "1.18.1",
@@ -60,6 +63,7 @@
     "fastify-type-provider-zod": "^6.0.0",
     "fishery": "^2.4.0",
     "@shipfox/biome": "1.8.2",
+    "@shipfox/depcruise": "1.0.2",
     "@shipfox/swc": "1.2.6",
     "@shipfox/ts-config": "1.3.8",
     "@shipfox/typescript": "1.1.7",
@@ -69,6 +73,7 @@
     "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/core/entities/provider.ts

@@ -1,6 +1,8 @@
 import type {
   IntegrationProvider as CoreIntegrationProvider,
   RegisteredIntegrationProvider as CoreRegisteredIntegrationProvider,
+  WebhookRequestProcessor,
+  WebhookRouteId,
 } from '@shipfox/api-integration-core-dto';
 import type {RouteExport} from '@shipfox/node-fastify';
 
@@ -17,5 +19,9 @@ export type {
   OpenAgentToolsSessionInput,
 } from '@shipfox/api-integration-core-dto';
 
-export type IntegrationProvider = CoreIntegrationProvider<string, RouteExport>;
+export type IntegrationProvider = CoreIntegrationProvider<string, RouteExport> & {
+  webhookProcessors?:
+    | Array<{routeIds: readonly WebhookRouteId[]; processor: WebhookRequestProcessor}>
+    | undefined;
+};
 export type RegisteredIntegrationProvider = CoreRegisteredIntegrationProvider<string, RouteExport>;

package/src/core/errors.ts

@@ -35,7 +35,10 @@ export class IntegrationConnectionAlreadyExistsError extends Error {
 }
 
 export class IntegrationCapabilityUnavailableError extends Error {
-  constructor(capability: IntegrationCapability, provider: IntegrationProviderKind) {
+  constructor(
+    public readonly capability: IntegrationCapability,
+    public readonly provider: IntegrationProviderKind,
+  ) {
     super(`Integration provider ${provider} does not expose ${capability}`);
   }
 }
@@ -47,9 +50,16 @@ export class IntegrationCheckoutUnsupportedError extends Error {
 }
 
 export class IntegrationProviderUnavailableError extends Error {
-  constructor(provider: IntegrationProviderKind) {
+  constructor(public readonly provider: IntegrationProviderKind) {
     super(`No integration provider registered for ${provider}`);
   }
 }
 
+export class WebhookProcessorNotConfiguredError extends Error {
+  constructor(public readonly routeId: string) {
+    super(`No webhook processor is configured for ${routeId}`);
+    this.name = 'WebhookProcessorNotConfiguredError';
+  }
+}
+
 export {ConnectionSlugConflictError, IntegrationProviderError, type IntegrationProviderErrorReason};

package/src/index.test.ts

@@ -0,0 +1,112 @@
+import type {
+  StoredWebhookRequest,
+  WebhookRequestProcessor,
+} from '@shipfox/api-integration-core-dto';
+import {createOutboxRegistry, type ModuleService, startModuleServices} from '@shipfox/node-module';
+import {createIntegrationsContext, WebhookProcessorNotConfiguredError} from './index.js';
+
+const request = {
+  schema_version: 1,
+  request_id: 'a8a44e12-f4bd-4bd1-82d4-ccdba70a9f3e',
+  route_id: 'github',
+  received_at: '2026-07-20T12:00:00.000Z',
+  method: 'POST',
+  path_parameters: {},
+  raw_query_string: '',
+  headers: {},
+  body: {encoding: 'base64', data: ''},
+} as const satisfies StoredWebhookRequest;
+
+describe('createIntegrationsContext', () => {
+  it('binds the composed direct-route processor to an optional delivery source', async () => {
+    const directProcessor: WebhookRequestProcessor = {
+      process: vi.fn().mockResolvedValue({outcome: 'processed', deliveryId: 'delivery-1'}),
+    };
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const service: ModuleService = {
+      name: 'queued-webhook-deliveries',
+      shutdownTimeoutMs: 1_000,
+      start: vi.fn().mockResolvedValue({finished: Promise.resolve(), stop}),
+    };
+    const deliverySource = {createService: vi.fn().mockReturnValue(service)};
+
+    const context = await createIntegrationsContext({
+      parts: [
+        {
+          provider: {provider: 'github', displayName: 'GitHub', adapters: {}},
+          webhookProcessors: [{routeIds: ['github'], processor: directProcessor}],
+        },
+      ],
+      webhookDeliverySource: deliverySource,
+    });
+
+    expect(context.module.services).toEqual([service]);
+    expect(deliverySource.createService).toHaveBeenCalledWith(context.webhookProcessor);
+
+    const result = await context.webhookProcessor.process(request);
+    const services = await startModuleServices({
+      services: context.module.services ?? [],
+      context: {outboxRegistry: createOutboxRegistry()},
+    });
+    await services.stop();
+
+    expect(result).toEqual({outcome: 'processed', deliveryId: 'delivery-1'});
+    expect(directProcessor.process).toHaveBeenCalledWith(request);
+    expect(stop).toHaveBeenCalledOnce();
+  });
+
+  it('does not register a service without a delivery source', async () => {
+    const context = await createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+    });
+
+    expect(context.module.services).toBeUndefined();
+  });
+
+  it('rejects a queued request with no registered processor', async () => {
+    const context = await createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+    });
+
+    const result = context.webhookProcessor.process(request);
+
+    await expect(result).rejects.toEqual(new WebhookProcessorNotConfiguredError('github'));
+  });
+
+  it('fails composition when more than one processor handles a route', async () => {
+    const processor: WebhookRequestProcessor = {
+      process: vi.fn().mockResolvedValue({outcome: 'processed', deliveryId: 'delivery-1'}),
+    };
+
+    const result = createIntegrationsContext({
+      parts: [
+        {
+          provider: {provider: 'github', displayName: 'GitHub', adapters: {}},
+          webhookProcessors: [
+            {routeIds: ['github'], processor},
+            {routeIds: ['github'], processor},
+          ],
+        },
+      ],
+    });
+
+    await expect(result).rejects.toThrow(
+      'Webhook processor is registered more than once for github',
+    );
+  });
+
+  it('fails composition when a configured delivery source is invalid', async () => {
+    const sourceError = new Error('WEBHOOK_QUEUE_URL is required');
+
+    const result = createIntegrationsContext({
+      parts: [{provider: {provider: 'github', displayName: 'GitHub', adapters: {}}}],
+      webhookDeliverySource: {
+        createService: () => {
+          throw sourceError;
+        },
+      },
+    });
+
+    await expect(result).rejects.toThrow(sourceError);
+  });
+});

package/src/index.ts

@@ -1,9 +1,18 @@
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {integrationsEventSchemas} from '@shipfox/api-integration-core-dto';
-import type {ShipfoxModule} from '@shipfox/node-module';
+import {
+  integrationsEventSchemas,
+  type StoredWebhookRequest,
+  type WebhookProcessingResult,
+  type WebhookRequestProcessor,
+  type WebhookRouteId,
+} from '@shipfox/api-integration-core-dto';
+import type {WorkflowsModuleClient} from '@shipfox/api-workflows-dto/inter-module';
+import type {WorkspacesInterModuleClient} from '@shipfox/api-workspaces-dto/inter-module';
+import type {ModuleService, ShipfoxModule} from '@shipfox/node-module';
 import {logger} from '@shipfox/node-opentelemetry';
 import type {IntegrationProvider} from '#core/entities/provider.js';
+import {WebhookProcessorNotConfiguredError} from '#core/errors.js';
 import {
   createIntegrationProviderRegistry,
   type IntegrationProviderRegistry,
@@ -16,15 +25,26 @@ import {getIntegrationConnectionById} from '#db/connections.js';
 import {db} from '#db/db.js';
 import {migrationsPath} from '#db/migrations.js';
 import {integrationsOutbox} from '#db/schema/outbox.js';
-import {createIntegrationRoutes, type LeasedAgentStepLoader} from '#presentation/routes/index.js';
+import {createIntegrationsInterModulePresentation} from '#presentation/inter-module.js';
+import {createIntegrationRoutes} from '#presentation/routes/index.js';
 import {loadEnabledProviderModules} from '#providers/modules.js';
-import type {IntegrationModuleParts, IntegrationProviderSecrets} from '#providers/types.js';
+import type {
+  IntegrationModuleParts,
+  IntegrationProviderSecrets,
+  WebhookProcessorRegistration,
+} from '#providers/types.js';
 import {createIntegrationsMaintenanceActivities} from '#temporal/activities/index.js';
 import {INTEGRATIONS_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const maintenanceWorkflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
 
+export type {
+  StoredWebhookRequest,
+  WebhookProcessingResult,
+  WebhookRequestProcessor,
+  WebhookRouteId,
+} from '@shipfox/api-integration-core-dto';
 export {
   buildProviderRepositoryId,
   MAX_REPOSITORY_FILE_BYTES,
@@ -63,6 +83,7 @@ export {
   IntegrationConnectionWorkspaceMismatchError,
   IntegrationProviderError,
   IntegrationProviderUnavailableError,
+  WebhookProcessorNotConfiguredError,
 } from '#core/errors.js';
 export type {
   AgentToolCallInput,
@@ -119,11 +140,21 @@ export interface CreateIntegrationsModuleOptions {
    */
   parts?: IntegrationModuleParts[] | undefined;
   secrets?: IntegrationProviderSecrets | undefined;
+  workspaces?: WorkspacesInterModuleClient | undefined;
   agentTools?:
     | {
-        loadLeasedAgentStep: LeasedAgentStepLoader;
+        workflows: WorkflowsModuleClient;
       }
     | undefined;
+  webhookDeliverySource?: WebhookDeliverySource | undefined;
+}
+
+/**
+ * Hosted runtimes implement this port to receive stored webhook requests. The
+ * integration module starts its returned service after migrations complete.
+ */
+export interface WebhookDeliverySource {
+  createService(processor: WebhookRequestProcessor): ModuleService;
 }
 
 export interface IntegrationsContext {
@@ -133,6 +164,7 @@ export interface IntegrationsContext {
     sourceControl: IntegrationSourceControlService;
   };
   sourceControl: IntegrationSourceControlService;
+  webhookProcessor: WebhookRequestProcessor;
   /**
    * Runs every enabled provider's one-shot boot-time tasks, after modules are initialized
    * (migrations done). Failures are isolated and logged, never rethrown, so a provider task
@@ -150,17 +182,41 @@ export async function createIntegrationsModule(
 export async function createIntegrationsContext(
   options: CreateIntegrationsModuleOptions = {},
 ): Promise<IntegrationsContext> {
+  const workspaces = options.workspaces;
   const parts: IntegrationModuleParts[] =
     options.parts ??
     (options.providers
-      ? options.providers.map((provider) => ({provider}))
-      : await loadEnabledProviderModules({secrets: options.secrets}));
+      ? options.providers.map((provider) => ({
+          provider,
+          webhookProcessors: provider.webhookProcessors,
+        }))
+      : await loadEnabledProviderModules({
+          secrets: options.secrets,
+          ...(workspaces
+            ? {
+                requireActiveWorkspaceMembership: (input: {
+                  workspaceId: string;
+                  userId: string;
+                  memberships: ReadonlyArray<
+                    import('@shipfox/api-auth-context').UserContextMembership
+                  >;
+                }) =>
+                  workspaces.requireActiveMembership({
+                    ...input,
+                    memberships: [...input.memberships],
+                  }),
+              }
+            : {}),
+        }));
 
   const registry = createIntegrationProviderRegistry(parts.map((part) => part.provider));
   const sourceControl = createSourceControlIntegrationService({
     registry,
     getIntegrationConnectionById,
   });
+  const webhookProcessor = createComposedWebhookProcessor(
+    parts.flatMap((part) => part.webhookProcessors ?? []),
+  );
 
   async function runStartupTasks(): Promise<void> {
     for (const task of parts.flatMap((part) => part.startupTasks ?? [])) {
@@ -175,6 +231,9 @@ export async function createIntegrationsContext(
 
   const module: ShipfoxModule = {
     name: 'integrations',
+    interModulePresentations: [
+      createIntegrationsInterModulePresentation({registry, sourceControl}),
+    ],
     startupTasks: runStartupTasks,
     database: [
       {db, migrationsPath},
@@ -183,7 +242,7 @@ export async function createIntegrationsContext(
     routes: createIntegrationRoutes(registry, sourceControl, {
       agentTools: options.agentTools
         ? {
-            loadLeasedAgentStep: options.agentTools.loadLeasedAgentStep,
+            workflows: options.agentTools.workflows,
             getIntegrationConnectionById,
           }
         : undefined,
@@ -207,7 +266,41 @@ export async function createIntegrationsContext(
       },
       ...parts.flatMap((part) => part.workers ?? []),
     ],
+    ...(options.webhookDeliverySource
+      ? {services: [options.webhookDeliverySource.createService(webhookProcessor)]}
+      : {}),
   };
 
-  return {module, registry, capabilities: {sourceControl}, sourceControl, runStartupTasks};
+  return {
+    module,
+    registry,
+    capabilities: {sourceControl},
+    sourceControl,
+    webhookProcessor,
+    runStartupTasks,
+  };
+}
+
+function createComposedWebhookProcessor(
+  registrations: WebhookProcessorRegistration[],
+): WebhookRequestProcessor {
+  const processors = new Map<WebhookRouteId, WebhookRequestProcessor>();
+  for (const registration of registrations) {
+    for (const routeId of registration.routeIds) {
+      if (processors.has(routeId)) {
+        throw new Error(`Webhook processor is registered more than once for ${routeId}`);
+      }
+      processors.set(routeId, registration.processor);
+    }
+  }
+
+  return {
+    async process(request: StoredWebhookRequest): Promise<WebhookProcessingResult> {
+      const processor = processors.get(request.route_id);
+      if (!processor) {
+        throw new WebhookProcessorNotConfiguredError(request.route_id);
+      }
+      return await processor.process(request);
+    },
+  };
 }

package/src/presentation/inter-module.ts

@@ -0,0 +1,155 @@
+import {integrationsInterModuleContract} from '@shipfox/api-integration-core-dto';
+import {
+  createInterModuleKnownError,
+  defineInterModulePresentation,
+  type InterModuleMethodContract,
+  type InterModulePresentation,
+} from '@shipfox/inter-module';
+import {
+  buildAgentToolCatalogs,
+  buildAgentToolSelectionCatalogs,
+  createWorkspaceConnectionSnapshotLoader,
+} from '#core/agent-tool-selection.js';
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationCheckoutUnsupportedError,
+  IntegrationConnectionInactiveError,
+  IntegrationConnectionNotFoundError,
+  IntegrationConnectionWorkspaceMismatchError,
+  IntegrationProviderError,
+  IntegrationProviderUnavailableError,
+} from '#core/errors.js';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {IntegrationSourceControlService} from '#core/source-control-service.js';
+import {getIntegrationConnectionById} from '#db/connections.js';
+
+export function createIntegrationsInterModulePresentation(params: {
+  registry: IntegrationProviderRegistry;
+  sourceControl: IntegrationSourceControlService;
+}): InterModulePresentation<typeof integrationsInterModuleContract> {
+  const contract = integrationsInterModuleContract;
+  return defineInterModulePresentation(contract, {
+    resolveSourceRepository: async (input) =>
+      await known(contract.methods.resolveSourceRepository, input, async () => {
+        const resolved = await params.sourceControl.resolveRepository(input);
+        return {
+          connection: {
+            id: resolved.connection.id,
+            provider: resolved.connection.provider,
+            slug: resolved.connection.slug,
+          },
+          repository: resolved.repository,
+        };
+      }),
+    listSourceFiles: async (input) =>
+      await known(
+        contract.methods.listSourceFiles,
+        input,
+        async () => await params.sourceControl.listFiles(input),
+      ),
+    fetchSourceFile: async (input) =>
+      await known(
+        contract.methods.fetchSourceFile,
+        input,
+        async () => await params.sourceControl.fetchFile(input),
+      ),
+    createCheckoutSpec: async (input) =>
+      await known(contract.methods.createCheckoutSpec, input, async () => {
+        const spec = await params.sourceControl.createCheckoutSpec(input);
+        return {
+          repositoryUrl: spec.repositoryUrl,
+          ref: spec.ref,
+          ...(spec.credentials
+            ? {
+                credentials: {
+                  ...spec.credentials,
+                  expiresAt: spec.credentials.expiresAt.toISOString(),
+                },
+              }
+            : {}),
+          ...(spec.gitAuthor === undefined ? {} : {gitAuthor: spec.gitAuthor}),
+        };
+      }),
+    getAgentToolsContext: async (input) =>
+      await known(contract.methods.getAgentToolsContext, input, async () => {
+        const [selectionCatalogs, catalogs, snapshot, defaultConnection] = await Promise.all([
+          buildAgentToolSelectionCatalogs(params.registry),
+          buildAgentToolCatalogs(params.registry),
+          createWorkspaceConnectionSnapshotLoader(params.registry)(input.workspaceId),
+          getIntegrationConnectionById(input.defaultConnectionId),
+        ]);
+        return {
+          selectionCatalogs: [...selectionCatalogs].map(([provider, value]) => ({
+            provider,
+            selectors: value.selectors.map((selector) => ({...selector})),
+          })),
+          catalogs: [...catalogs].map(([provider, tools]) => ({
+            provider,
+            tools: tools.map(({methods, ...tool}) => ({
+              ...tool,
+              ...(methods === undefined ? {} : {methods: methods.map((method) => ({...method}))}),
+            })),
+          })),
+          workspaceConnections: [...snapshot].map(([slug, value]) => ({
+            slug,
+            ...value,
+            capabilities: [...value.capabilities],
+          })),
+          defaultConnection: defaultConnection
+            ? {
+                id: defaultConnection.id,
+                slug: defaultConnection.slug,
+                provider: defaultConnection.provider,
+              }
+            : null,
+        };
+      }),
+  });
+}
+
+async function known<Output>(
+  method: InterModuleMethodContract,
+  input: {connectionId?: string; defaultConnectionId?: string},
+  operation: () => Promise<Output>,
+): Promise<Output> {
+  try {
+    return await operation();
+  } catch (error) {
+    throw mapError(method, input, error);
+  }
+}
+function mapError(
+  method: InterModuleMethodContract,
+  input: {connectionId?: string; defaultConnectionId?: string},
+  error: unknown,
+): unknown {
+  if (error instanceof IntegrationConnectionNotFoundError)
+    return createInterModuleKnownError(method, 'connection-not-found', {
+      connectionId: input.connectionId ?? input.defaultConnectionId,
+    });
+  if (error instanceof IntegrationConnectionInactiveError)
+    return createInterModuleKnownError(method, 'connection-inactive', {
+      connectionId: input.connectionId,
+    });
+  if (error instanceof IntegrationConnectionWorkspaceMismatchError)
+    return createInterModuleKnownError(method, 'connection-workspace-mismatch', {
+      connectionId: input.connectionId,
+    });
+  if (error instanceof IntegrationProviderUnavailableError)
+    return createInterModuleKnownError(method, 'provider-unavailable', {provider: error.provider});
+  if (error instanceof IntegrationCapabilityUnavailableError)
+    return createInterModuleKnownError(method, 'capability-unavailable', {
+      provider: error.provider,
+      capability: error.capability,
+    });
+  if (error instanceof IntegrationCheckoutUnsupportedError)
+    return createInterModuleKnownError(method, 'checkout-unsupported', {provider: error.provider});
+  if (error instanceof IntegrationProviderError)
+    return createInterModuleKnownError(method, 'provider-failure', {
+      reason: error.reason,
+      ...(error.retryAfterSeconds === undefined
+        ? {}
+        : {retryAfterSeconds: error.retryAfterSeconds}),
+    });
+  return error;
+}

package/src/presentation/routes/agent-tools-gateway/index.ts

@@ -13,6 +13,7 @@ import {
 } from './resolve-authorized-tools.js';
 
 export type {LeasedAgentStepLoader} from './resolve-authorized-tools.js';
+export {createWorkflowsLeasedAgentStepLoader} from './resolve-authorized-tools.js';
 
 export interface CreateAgentToolsGatewayRoutesParams {
   loadLeasedAgentStep: LeasedAgentStepLoader;

package/src/presentation/routes/agent-tools-gateway/resolve-authorized-tools.test.ts

@@ -1,4 +1,6 @@
 import {setLeasedJobContext} from '@shipfox/api-auth-context';
+import {workflowsInterModuleContract} from '@shipfox/api-workflows-dto/inter-module';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
 import {createIntegrationProviderRegistry} from '#core/providers/registry.js';
 import {
   agentStepConfig,
@@ -9,6 +11,7 @@ import {
   registryWithAgentTools,
 } from '#test/agent-tools-gateway-helpers.js';
 import {
+  createWorkflowsLeasedAgentStepLoader,
   mcpToolName,
   narrowMethodEnum,
   resolveAuthorizedIntegrationTools,
@@ -16,6 +19,39 @@ import {
 } from './resolve-authorized-tools.js';
 
 describe('resolveAuthorizedIntegrationTools', () => {
+  it.each([
+    ['lease-not-active', 404],
+    ['step-not-found', 404],
+    ['job-not-found', 404],
+    ['step-attempt-mismatch', 409],
+    ['step-not-running', 409],
+    ['leased-step-not-agent', 409],
+    ['agent-step-config-invalid', 409],
+  ] as const)('maps %s from Workflows to HTTP %i', async (code, status) => {
+    const request = {};
+    const lease = leaseContext();
+    setLeasedJobContext(request, lease);
+    const workflows = {
+      getLeasedAgentToolContext: () =>
+        Promise.reject(
+          createInterModuleKnownError(
+            workflowsInterModuleContract.methods.getLeasedAgentToolContext,
+            code,
+            {},
+          ),
+        ),
+    };
+    const loadLeasedAgentStep = createWorkflowsLeasedAgentStepLoader(workflows as never);
+
+    const error = await loadLeasedAgentStep({
+      request,
+      stepId: lease.currentStepId as string,
+      attempt: lease.currentStepAttempt as number,
+    }).catch((error: unknown) => error);
+
+    expect(error).toMatchObject({code, status});
+  });
+
   it('resolves namespaced tools with live descriptions and Anthropic-compatible method schemas', async () => {
     const request = {};
     const lease = leaseContext();