@shipfox/api-integration-core 12.4.0 → 12.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "12.4.0",
+  "version": "12.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,17 +26,17 @@
     "zod": "^4.4.3",
     "@shipfox/api-agent-dto": "12.2.0",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-workflows-dto": "12.3.0",
+    "@shipfox/api-workflows-dto": "12.5.0",
     "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-integration-spi": "1.1.0",
+    "@shipfox/api-integration-spi": "1.1.1",
     "@shipfox/api-workspaces-dto": "12.0.0",
-    "@shipfox/api-integration-gitea": "12.3.0",
-    "@shipfox/api-integration-github": "12.3.0",
-    "@shipfox/api-integration-jira": "12.4.0",
-    "@shipfox/api-integration-linear": "12.3.0",
-    "@shipfox/api-integration-sentry": "12.3.0",
-    "@shipfox/api-integration-slack": "12.3.0",
-    "@shipfox/api-integration-webhook": "12.3.0",
+    "@shipfox/api-integration-gitea": "12.5.0",
+    "@shipfox/api-integration-github": "12.5.0",
+    "@shipfox/api-integration-jira": "12.5.0",
+    "@shipfox/api-integration-linear": "12.5.0",
+    "@shipfox/api-integration-sentry": "12.5.0",
+    "@shipfox/api-integration-slack": "12.5.0",
+    "@shipfox/api-integration-webhook": "12.5.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",

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

@@ -9,6 +9,7 @@ import {
 } from '@shipfox/api-auth-context';
 import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
 import type {FastifyInstance, FastifyRequest} from 'fastify';
+import {IntegrationProviderError} from '#core/errors.js';
 import {
   agentStepConfig,
   catalogTool,
@@ -227,13 +228,19 @@ describe('agent tools gateway route', () => {
     });
   });
 
-  it('returns bounded MCP errors when provider dispatch fails', async () => {
+  it('returns the provider message and terminal code for rejected calls', async () => {
     const lease = leaseContext({workspaceId: 'workspace-1'});
     const integration = materializedIntegration({connectionId: 'connection-1'});
     leases.set('provider-error-lease', lease);
+    const providerError = new IntegrationProviderError(
+      'provider-rejected',
+      'commit_id is missing',
+      undefined,
+      422,
+    );
     const app = await createGatewayApp({
       registry: registryWithAgentTools([catalogTool()], {
-        callError: new Error('remote provider leaked implementation detail'),
+        callError: providerError,
       }),
       loadLeasedAgentStep: async () => ({
         workspaceId: lease.workspaceId,
@@ -269,8 +276,8 @@ describe('agent tools gateway route', () => {
 
     expect(result).toEqual({
       isError: true,
-      content: [{type: 'text', text: 'Integration provider call failed'}],
-      structuredContent: {code: 'provider-unavailable'},
+      content: [{type: 'text', text: 'commit_id is missing'}],
+      structuredContent: {code: 'provider-rejected', status: 422},
     });
   });
 

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

@@ -0,0 +1,107 @@
+import type {reportError as reportErrorType} from '@shipfox/node-error-monitoring';
+import type {logger as loggerFactoryType} from '@shipfox/node-opentelemetry';
+import {IntegrationProviderError} from '#core/errors.js';
+import {
+  catalogTool,
+  connection,
+  materializedIntegration,
+  materializedTool,
+  registryWithAgentTools,
+} from '#test/agent-tools-gateway-helpers.js';
+import {createIntegrationToolDispatcher} from './dispatch.js';
+import type {AuthorizedIntegrationTool} from './resolve-authorized-tools.js';
+
+const dispatchMocks = vi.hoisted(() => ({
+  loggerError: vi.fn(),
+  reportError: vi.fn(),
+}));
+
+const loggerFactory = (() => ({
+  error: dispatchMocks.loggerError,
+})) as unknown as typeof loggerFactoryType;
+const reportError = dispatchMocks.reportError as unknown as typeof reportErrorType;
+
+describe('createIntegrationToolDispatcher', () => {
+  beforeEach(() => {
+    dispatchMocks.loggerError.mockReset();
+    dispatchMocks.reportError.mockReset();
+  });
+
+  it('preserves terminal provider errors without reporting them as outages', async () => {
+    const providerError = new IntegrationProviderError(
+      'provider-rejected',
+      'commit_id is missing',
+      undefined,
+      422,
+    );
+    const dispatch = createDispatcher(providerError);
+
+    const result = await dispatch({
+      authorizedTool: authorizedTool(),
+      arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'commit_id is missing'}],
+      structuredContent: {code: 'provider-rejected', status: 422},
+    });
+    expect(dispatchMocks.loggerError).not.toHaveBeenCalled();
+    expect(dispatchMocks.reportError).not.toHaveBeenCalled();
+  });
+
+  it('reports provider outages while preserving their message and status', async () => {
+    const providerError = new IntegrationProviderError(
+      'provider-unavailable',
+      'GitHub returned HTTP 503',
+      undefined,
+      503,
+    );
+    const dispatch = createDispatcher(providerError);
+
+    const result = await dispatch({
+      authorizedTool: authorizedTool(),
+      arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'GitHub returned HTTP 503'}],
+      structuredContent: {code: 'provider-unavailable', status: 503},
+    });
+    expect(dispatchMocks.loggerError).toHaveBeenCalledWith(
+      {err: providerError, provider: 'github'},
+      'Integration agent tool provider was unavailable',
+    );
+    expect(dispatchMocks.reportError).toHaveBeenCalledWith(providerError, {
+      boundary: 'integration.agent-tool',
+    });
+  });
+});
+
+function createDispatcher(callError: IntegrationProviderError) {
+  return createIntegrationToolDispatcher(
+    {
+      registry: registryWithAgentTools([catalogTool()], {callError}),
+    },
+    {logger: loggerFactory, reportError},
+  );
+}
+
+function authorizedTool(): AuthorizedIntegrationTool {
+  const integration = materializedIntegration({connectionId: 'connection-1'});
+  const tool = materializedTool();
+  return {
+    mcpName: 'github_main__issue_read',
+    integration,
+    tool,
+    connection: connection({
+      id: integration.connectionId,
+      workspaceId: 'workspace-1',
+      slug: integration.connectionSlug,
+    }),
+    description: 'Read issue metadata from GitHub.',
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+  };
+}

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

@@ -15,17 +15,33 @@ export interface CreateIntegrationToolDispatcherParams {
   registry: IntegrationProviderRegistry;
 }
 
+export interface IntegrationToolDispatcherDependencies {
+  logger?: typeof logger;
+  reportError?: typeof reportError;
+}
+
 const timeoutErrorPattern = /timed?\s*out|timeout/i;
 const credentialErrorNamePattern = /Token|Credential|Secret|AccessToken/;
 
 export function createIntegrationToolDispatcher(
   params: CreateIntegrationToolDispatcherParams,
+  dependencies: IntegrationToolDispatcherDependencies = {},
 ): IntegrationToolDispatcher {
-  return (input) => dispatchIntegrationToolCall({...input, registry: params.registry});
+  return (input) =>
+    dispatchIntegrationToolCall({
+      ...input,
+      registry: params.registry,
+      logger: dependencies.logger ?? logger,
+      reportError: dependencies.reportError ?? reportError,
+    });
 }
 
 async function dispatchIntegrationToolCall(
-  input: IntegrationToolDispatchInput & {registry: IntegrationProviderRegistry},
+  input: IntegrationToolDispatchInput & {
+    registry: IntegrationProviderRegistry;
+    logger: typeof logger;
+    reportError: typeof reportError;
+  },
 ): Promise<CallToolResult> {
   let session: AgentToolSession<CallToolResult> | undefined;
 
@@ -52,15 +68,17 @@ async function dispatchIntegrationToolCall(
   } catch (error) {
     const result = errorResult(error);
     if (result.code === 'provider-unavailable') {
-      logger().error(
-        {err: error, provider: input.authorizedTool.integration.provider},
-        'Integration agent tool provider was unavailable',
-      );
-      reportError(error, {boundary: 'integration.agent-tool'});
+      input
+        .logger()
+        .error(
+          {err: error, provider: input.authorizedTool.integration.provider},
+          'Integration agent tool provider was unavailable',
+        );
+      input.reportError(error, {boundary: 'integration.agent-tool'});
     }
     return toolError(result);
   } finally {
-    await closeSession(session);
+    await closeSession(session, input.logger, input.reportError);
   }
 }
 
@@ -90,21 +108,36 @@ function agentToolCatalogEntry(input: IntegrationToolDispatchInput): AgentToolCa
   };
 }
 
-async function closeSession(session: {close?(): Promise<void>} | undefined): Promise<void> {
+async function closeSession(
+  session: {close?(): Promise<void>} | undefined,
+  loggerFactory: typeof logger,
+  reportErrorFn: typeof reportError,
+): Promise<void> {
   try {
     await session?.close?.();
   } catch (error) {
     // Cleanup must not mask the tool result returned to the runner.
-    logger().error({err: error}, 'Failed to close integration agent tool session');
-    reportError(error, {boundary: 'integration.agent-tool', operation: 'close-session'});
+    loggerFactory().error({err: error}, 'Failed to close integration agent tool session');
+    reportErrorFn(error, {boundary: 'integration.agent-tool', operation: 'close-session'});
   }
 }
 
-function errorResult(error: unknown): {code: string; message: string} {
+interface IntegrationToolError {
+  code: string;
+  message: string;
+  retryAfterSeconds?: number | undefined;
+  status?: number | undefined;
+}
+
+function errorResult(error: unknown): IntegrationToolError {
   if (error instanceof IntegrationProviderError) {
     return {
       code: error.reason,
-      message: `Integration provider error: ${error.reason}`,
+      message: error.message,
+      ...(error.retryAfterSeconds === undefined
+        ? {}
+        : {retryAfterSeconds: error.retryAfterSeconds}),
+      ...(error.status === undefined ? {} : {status: error.status}),
     };
   }
 
@@ -142,10 +175,16 @@ function isCredentialError(error: unknown): boolean {
   return credentialErrorNamePattern.test(error.name);
 }
 
-function toolError(params: {code: string; message: string}): CallToolResult {
+function toolError(params: IntegrationToolError): CallToolResult {
   return {
     isError: true,
     content: [{type: 'text', text: params.message}],
-    structuredContent: {code: params.code},
+    structuredContent: {
+      code: params.code,
+      ...(params.retryAfterSeconds === undefined
+        ? {}
+        : {retryAfterSeconds: params.retryAfterSeconds}),
+      ...(params.status === undefined ? {} : {status: params.status}),
+    },
   };
 }

package/src/presentation/routes/errors.ts

@@ -28,6 +28,7 @@ function isProviderError(error: unknown): error is IntegrationProviderError {
         error.reason === 'rate-limited' ||
         error.reason === 'timeout' ||
         error.reason === 'provider-unavailable' ||
+        error.reason === 'provider-rejected' ||
         error.reason === 'malformed-provider-response' ||
         error.reason === 'content-too-large' ||
         error.reason === 'too-many-files'))