@shipfox/api-integration-core 12.5.0 → 12.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "12.5.0",
+  "version": "12.6.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,12 +26,12 @@
     "zod": "^4.4.3",
     "@shipfox/api-agent-dto": "12.2.0",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-workflows-dto": "12.5.0",
+    "@shipfox/api-workflows-dto": "12.6.0",
     "@shipfox/api-integration-core-dto": "12.2.0",
     "@shipfox/api-integration-spi": "1.1.1",
     "@shipfox/api-workspaces-dto": "12.0.0",
     "@shipfox/api-integration-gitea": "12.5.0",
-    "@shipfox/api-integration-github": "12.5.0",
+    "@shipfox/api-integration-github": "12.6.0",
     "@shipfox/api-integration-jira": "12.5.0",
     "@shipfox/api-integration-linear": "12.5.0",
     "@shipfox/api-integration-sentry": "12.5.0",

package/src/metrics/instance.ts

@@ -1,3 +1,4 @@
+import type {IntegrationProviderErrorReason} from '@shipfox/api-integration-spi';
 import {instanceMetrics} from '@shipfox/node-opentelemetry';
 
 const meter = instanceMetrics.getMeter('integrations');
@@ -8,13 +9,42 @@ export type IntegrationAgentToolCallOutcome =
   | 'invalid-request'
   | 'exception';
 
+export type IntegrationAgentToolCallErrorCode =
+  | 'invalid-request'
+  | 'unknown'
+  | 'provider-timeout'
+  | 'credentials-unavailable'
+  | IntegrationProviderErrorReason;
+
+export type IntegrationAgentToolCallErrorLabel = IntegrationAgentToolCallErrorCode | 'none';
+
+const integrationAgentToolCallErrorCodes = new Set<string>([
+  'invalid-request',
+  'unknown',
+  'provider-timeout',
+  'credentials-unavailable',
+  'repository-not-found',
+  'installation-not-found',
+  'file-not-found',
+  'access-denied',
+  'rate-limited',
+  'timeout',
+  'provider-unavailable',
+  'provider-rejected',
+  'malformed-provider-response',
+  'content-too-large',
+  'too-many-files',
+]);
+
 const agentToolCallCount = meter.createCounter<{
   provider: string;
   tool: string;
   method: string;
   outcome: IntegrationAgentToolCallOutcome;
+  error_code: IntegrationAgentToolCallErrorLabel;
 }>('integrations_agent_tool_call', {
-  description: 'Integration agent tool calls by provider, tool, method, and outcome',
+  description:
+    'Integration agent tool calls by provider, tool, method, outcome, and bounded error code',
 });
 
 function recordMetric(record: () => void): void {
@@ -30,6 +60,15 @@ export function recordIntegrationAgentToolCall(params: {
   tool: string;
   method: string;
   outcome: IntegrationAgentToolCallOutcome;
+  error_code: IntegrationAgentToolCallErrorLabel;
 }): void {
   recordMetric(() => agentToolCallCount.add(1, params));
 }
+
+export function normalizeIntegrationAgentToolCallErrorCode(
+  value: unknown,
+): IntegrationAgentToolCallErrorCode {
+  return typeof value === 'string' && integrationAgentToolCallErrorCodes.has(value)
+    ? (value as IntegrationAgentToolCallErrorCode)
+    : 'unknown';
+}

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

@@ -43,6 +43,7 @@ describe('integration tool call audit', () => {
       },
       method: 'get',
       outcome: 'success',
+      errorCode: 'none',
     });
 
     expect(recordMetric).toHaveBeenCalledWith({
@@ -50,6 +51,7 @@ describe('integration tool call audit', () => {
       tool: 'issue_read',
       method: 'get',
       outcome: 'success',
+      error_code: 'none',
     });
     expect(logInfo).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -65,6 +67,7 @@ describe('integration tool call audit', () => {
         toolId: 'issue_read',
         method: 'get',
         outcome: 'success',
+        errorCode: 'none',
         argumentSummary: {
           keys: ['owner', 'repo', 'token'],
           serializedSizeBytes: expect.any(Number),
@@ -75,6 +78,54 @@ describe('integration tool call audit', () => {
     expect(JSON.stringify(logInfo.mock.calls)).not.toContain('must-not-appear');
   });
 
+  it('records bounded provider error details without logging arguments', () => {
+    const recordMetric = vi.fn();
+    const logInfo = vi.fn();
+    const lease = leaseContext({jobId: 'job-1', workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    const tool = materializedTool();
+    const recorder = createIntegrationToolCallRecorder(lease, {recordMetric, logInfo});
+
+    recorder({
+      authorizedTool: {
+        mcpName: 'github_main__issue_read',
+        integration,
+        tool,
+        connection: connection({
+          id: 'connection-1',
+          workspaceId: 'workspace-1',
+          slug: integration.connectionSlug,
+        }),
+        description: 'Read issues',
+        inputSchema: tool.inputSchema,
+      },
+      arguments: {repo: 'private-repository', token: 'must-not-appear'},
+      method: 'get',
+      outcome: 'tool-error',
+      errorCode: 'provider-rejected',
+      providerStatus: 422,
+    });
+
+    expect(recordMetric).toHaveBeenCalledWith({
+      provider: 'github',
+      tool: 'issue_read',
+      method: 'get',
+      outcome: 'tool-error',
+      error_code: 'provider-rejected',
+    });
+    expect(logInfo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jobId: 'job-1',
+        workspaceId: 'workspace-1',
+        errorCode: 'provider-rejected',
+        providerStatus: 422,
+      }),
+      'integration tool call audited',
+    );
+    expect(JSON.stringify(logInfo.mock.calls)).not.toContain('private-repository');
+    expect(JSON.stringify(logInfo.mock.calls)).not.toContain('must-not-appear');
+  });
+
   it('summarizes arguments without values', () => {
     const summary = summarizeIntegrationToolArguments({z: 'secret', a: 1});
 

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

@@ -1,11 +1,14 @@
 import type {LeasedJobContext} from '@shipfox/api-auth-context';
 import {logger} from '@shipfox/node-opentelemetry';
 import {
+  type IntegrationAgentToolCallErrorLabel,
   type IntegrationAgentToolCallOutcome,
   recordIntegrationAgentToolCall,
 } from '#metrics/index.js';
 import type {AuthorizedIntegrationTool} from './resolve-authorized-tools.js';
 
+export type {IntegrationAgentToolCallErrorCode} from '#metrics/index.js';
+
 export const UNKNOWN_TOOL_LABEL = 'unknown';
 export const NO_METHOD_LABEL = 'none';
 export const INVALID_METHOD_LABEL = 'invalid';
@@ -20,6 +23,8 @@ export interface IntegrationToolCallAuditRecord {
   arguments: unknown;
   method: string;
   outcome: IntegrationAgentToolCallOutcome;
+  errorCode: IntegrationAgentToolCallErrorLabel;
+  providerStatus?: number | undefined;
 }
 
 export type IntegrationToolCallRecorder = (record: IntegrationToolCallAuditRecord) => void;
@@ -47,6 +52,7 @@ export function createIntegrationToolCallRecorder(
       tool: toolId,
       method: record.method,
       outcome: record.outcome,
+      error_code: record.errorCode,
     });
 
     logInfo(
@@ -63,6 +69,8 @@ export function createIntegrationToolCallRecorder(
         toolId,
         method: record.method,
         outcome: record.outcome,
+        errorCode: record.errorCode,
+        ...(record.providerStatus === undefined ? {} : {providerStatus: record.providerStatus}),
         argumentSummary: summarizeIntegrationToolArguments(record.arguments),
       },
       'integration tool call audited',

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

@@ -4,6 +4,7 @@ import {IntegrationProviderError} from '#core/errors.js';
 import {
   catalogTool,
   connection,
+  leaseContext,
   materializedIntegration,
   materializedTool,
   registryWithAgentTools,
@@ -39,6 +40,7 @@ describe('createIntegrationToolDispatcher', () => {
     const result = await dispatch({
       authorizedTool: authorizedTool(),
       arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      method: 'get',
     });
 
     expect(result).toEqual({
@@ -62,6 +64,7 @@ describe('createIntegrationToolDispatcher', () => {
     const result = await dispatch({
       authorizedTool: authorizedTool(),
       arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      method: 'get',
     });
 
     expect(result).toEqual({
@@ -70,19 +73,76 @@ describe('createIntegrationToolDispatcher', () => {
       structuredContent: {code: 'provider-unavailable', status: 503},
     });
     expect(dispatchMocks.loggerError).toHaveBeenCalledWith(
-      {err: providerError, provider: 'github'},
+      expect.objectContaining({
+        err: providerError,
+        provider: 'github',
+        toolId: 'issue_read',
+        method: 'get',
+        errorCode: 'provider-unavailable',
+        providerStatus: 503,
+      }),
       'Integration agent tool provider was unavailable',
     );
+    expect(dispatchMocks.loggerError.mock.calls[0]?.[0]).toMatchObject({
+      jobId: 'job-1',
+      jobExecutionId: 'execution-1',
+      workflowRunId: 'run-1',
+      workflowRunAttemptId: 'attempt-1',
+      workspaceId: 'workspace-1',
+      currentStepId: 'step-1',
+      currentStepAttempt: 2,
+      connectionId: 'connection-1',
+    });
     expect(dispatchMocks.reportError).toHaveBeenCalledWith(providerError, {
       boundary: 'integration.agent-tool',
     });
   });
+
+  it('classifies unrecognized failures as unknown instead of provider outages', async () => {
+    const internalError = new Error('request timeout configuration is invalid');
+    const dispatch = createDispatcher(internalError);
+
+    const result = await dispatch({
+      authorizedTool: authorizedTool(),
+      arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      method: 'get',
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Integration tool call failed'}],
+      structuredContent: {code: 'unknown'},
+    });
+    expect(dispatchMocks.loggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        err: internalError,
+        provider: 'github',
+        toolId: 'issue_read',
+        method: 'get',
+        errorCode: 'unknown',
+      }),
+      'Integration agent tool call failed',
+    );
+    expect(dispatchMocks.loggerError.mock.calls[0]?.[0]).not.toHaveProperty('providerStatus');
+    expect(dispatchMocks.reportError).toHaveBeenCalledWith(internalError, {
+      boundary: 'integration.agent-tool',
+    });
+  });
 });
 
-function createDispatcher(callError: IntegrationProviderError) {
+function createDispatcher(callError: unknown) {
   return createIntegrationToolDispatcher(
     {
       registry: registryWithAgentTools([catalogTool()], {callError}),
+      lease: leaseContext({
+        jobId: 'job-1',
+        jobExecutionId: 'execution-1',
+        workflowRunId: 'run-1',
+        workflowRunAttemptId: 'attempt-1',
+        workspaceId: 'workspace-1',
+        currentStepId: 'step-1',
+        currentStepAttempt: 2,
+      }),
     },
     {logger: loggerFactory, reportError},
   );

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

@@ -1,4 +1,5 @@
 import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js';
+import type {LeasedJobContext} from '@shipfox/api-auth-context';
 import {reportError} from '@shipfox/node-error-monitoring';
 import {logger} from '@shipfox/node-opentelemetry';
 import {IntegrationProviderError} from '#core/errors.js';
@@ -9,10 +10,13 @@ import type {
   AgentToolsProvider,
 } from '#core/providers/agent-tools.js';
 import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {IntegrationAgentToolCallErrorCode} from '#metrics/index.js';
+import {NO_METHOD_LABEL} from './audit.js';
 import type {IntegrationToolDispatcher, IntegrationToolDispatchInput} from './mcp-server.js';
 
 export interface CreateIntegrationToolDispatcherParams {
   registry: IntegrationProviderRegistry;
+  lease?: LeasedJobContext | undefined;
 }
 
 export interface IntegrationToolDispatcherDependencies {
@@ -20,7 +24,8 @@ export interface IntegrationToolDispatcherDependencies {
   reportError?: typeof reportError;
 }
 
-const timeoutErrorPattern = /timed?\s*out|timeout/i;
+const timeoutErrorNamePattern = /timed?\s*out|timeout/i;
+const mcpRequestTimeoutMessagePattern = /^MCP error -32001:\s*Request timed out\b/i;
 const credentialErrorNamePattern = /Token|Credential|Secret|AccessToken/;
 
 export function createIntegrationToolDispatcher(
@@ -31,6 +36,7 @@ export function createIntegrationToolDispatcher(
     dispatchIntegrationToolCall({
       ...input,
       registry: params.registry,
+      lease: params.lease,
       logger: dependencies.logger ?? logger,
       reportError: dependencies.reportError ?? reportError,
     });
@@ -39,6 +45,7 @@ export function createIntegrationToolDispatcher(
 async function dispatchIntegrationToolCall(
   input: IntegrationToolDispatchInput & {
     registry: IntegrationProviderRegistry;
+    lease?: LeasedJobContext | undefined;
     logger: typeof logger;
     reportError: typeof reportError;
   },
@@ -67,13 +74,18 @@ async function dispatchIntegrationToolCall(
     });
   } catch (error) {
     const result = errorResult(error);
-    if (result.code === 'provider-unavailable') {
-      input
-        .logger()
-        .error(
-          {err: error, provider: input.authorizedTool.integration.provider},
-          'Integration agent tool provider was unavailable',
-        );
+    if (result.code === 'provider-unavailable' || result.code === 'unknown') {
+      input.logger().error(
+        {
+          ...toolCallLogContext(input),
+          err: error,
+          errorCode: result.code,
+          ...(result.status === undefined ? {} : {providerStatus: result.status}),
+        },
+        result.code === 'provider-unavailable'
+          ? 'Integration agent tool provider was unavailable'
+          : 'Integration agent tool call failed',
+      );
       input.reportError(error, {boundary: 'integration.agent-tool'});
     }
     return toolError(result);
@@ -82,6 +94,28 @@ async function dispatchIntegrationToolCall(
   }
 }
 
+function toolCallLogContext(
+  input: IntegrationToolDispatchInput & {lease?: LeasedJobContext | undefined},
+): Record<string, unknown> {
+  return {
+    ...(input.lease === undefined
+      ? {}
+      : {
+          jobId: input.lease.jobId,
+          jobExecutionId: input.lease.jobExecutionId,
+          workflowRunId: input.lease.workflowRunId,
+          workflowRunAttemptId: input.lease.workflowRunAttemptId,
+          workspaceId: input.lease.workspaceId,
+          currentStepId: input.lease.currentStepId,
+          currentStepAttempt: input.lease.currentStepAttempt,
+        }),
+    connectionId: input.authorizedTool.connection.id,
+    provider: input.authorizedTool.integration.provider,
+    toolId: input.authorizedTool.tool.id,
+    method: input.method ?? NO_METHOD_LABEL,
+  };
+}
+
 function agentToolCatalogEntry(input: IntegrationToolDispatchInput): AgentToolCatalogEntry {
   const {tool, description, inputSchema, outputSchema} = input.authorizedTool;
   return {
@@ -123,7 +157,7 @@ async function closeSession(
 }
 
 interface IntegrationToolError {
-  code: string;
+  code: IntegrationAgentToolCallErrorCode;
   message: string;
   retryAfterSeconds?: number | undefined;
   status?: number | undefined;
@@ -156,8 +190,8 @@ function errorResult(error: unknown): IntegrationToolError {
   }
 
   return {
-    code: 'provider-unavailable',
-    message: 'Integration provider call failed',
+    code: 'unknown',
+    message: 'Integration tool call failed',
   };
 }
 
@@ -165,8 +199,8 @@ function isTimeoutError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
   return (
     error.name === 'AbortError' ||
-    timeoutErrorPattern.test(error.name) ||
-    timeoutErrorPattern.test(error.message)
+    timeoutErrorNamePattern.test(error.name) ||
+    (error.name === 'McpError' && mcpRequestTimeoutMessagePattern.test(error.message))
   );
 }
 

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

@@ -26,8 +26,6 @@ export interface CreateAgentToolsGatewayRoutesParams {
 export function createAgentToolsGatewayRoutes(
   params: CreateAgentToolsGatewayRoutesParams,
 ): RouteGroup {
-  const dispatchIntegrationToolCall = createIntegrationToolDispatcher({registry: params.registry});
-
   return {
     prefix: '/runs/jobs/current/integration-tools',
     auth: AUTH_LEASED_JOB,
@@ -37,6 +35,7 @@ export function createAgentToolsGatewayRoutes(
         path: '/mcp',
         description: 'Gateway MCP endpoint for integration-backed agent tools',
         handler: async (request, reply) => {
+          const lease = requireLeasedJobContext(request);
           const authorizedTools = await resolveAuthorizedIntegrationTools({
             request,
             loadLeasedAgentStep: params.loadLeasedAgentStep,
@@ -45,8 +44,8 @@ export function createAgentToolsGatewayRoutes(
           });
           const server = buildAgentToolsMcpServer({
             authorizedTools,
-            dispatch: dispatchIntegrationToolCall,
-            recordCall: createIntegrationToolCallRecorder(requireLeasedJobContext(request)),
+            dispatch: createIntegrationToolDispatcher({registry: params.registry, lease}),
+            recordCall: createIntegrationToolCallRecorder(lease),
           });
           const transport = new StreamableHTTPServerTransport();
 

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

@@ -54,6 +54,7 @@ describe('buildAgentToolsMcpServer', () => {
         }),
         method: 'get',
         outcome: 'success',
+        errorCode: 'none',
       },
     ]);
   });
@@ -93,6 +94,7 @@ describe('buildAgentToolsMcpServer', () => {
       {
         method: expectedMethod,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       },
     ]);
     if (expectedToolId) {
@@ -128,7 +130,9 @@ describe('buildAgentToolsMcpServer', () => {
         arguments: {method: 'ignored'},
       }),
     );
-    expect(records).toMatchObject([{method: NO_METHOD_LABEL, outcome: 'success'}]);
+    expect(records).toMatchObject([
+      {method: NO_METHOD_LABEL, outcome: 'success', errorCode: 'none'},
+    ]);
   });
 
   it('defaults omitted arguments to an empty object for optional-argument tools', async () => {
@@ -179,7 +183,7 @@ describe('buildAgentToolsMcpServer', () => {
         arguments: expect.objectContaining({issue_number: 'not-an-integer'}),
       }),
     );
-    expect(records).toMatchObject([{method: 'get', outcome: 'success'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'success', errorCode: 'none'}]);
   });
 
   it('records tool-error when dispatch returns an error result', async () => {
@@ -204,7 +208,7 @@ describe('buildAgentToolsMcpServer', () => {
     await close();
 
     expect(result.isError).toBe(true);
-    expect(records).toMatchObject([{method: 'get', outcome: 'tool-error'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'tool-error', errorCode: 'unknown'}]);
   });
 
   it('records exception before rethrowing dispatcher failures', async () => {
@@ -227,7 +231,40 @@ describe('buildAgentToolsMcpServer', () => {
     ).rejects.toThrow('MCP error -32603');
     await close();
 
-    expect(records).toMatchObject([{method: 'get', outcome: 'exception'}]);
+    expect(records).toMatchObject([{method: 'get', outcome: 'exception', errorCode: 'unknown'}]);
+  });
+
+  it('records bounded provider error details returned by the dispatcher', async () => {
+    const dispatch = vi.fn(async () => ({
+      isError: true,
+      content: [{type: 'text' as const, text: 'provider rejected call'}],
+      structuredContent: {code: 'provider-rejected', status: 422},
+    }));
+    const records: Parameters<
+      NonNullable<Parameters<typeof buildAgentToolsMcpServer>[0]['recordCall']>
+    >[0][] = [];
+    const {client, close} = await connectClient(dispatch, defaultAuthorizedTools(), (record) =>
+      records.push(record),
+    );
+
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(records).toMatchObject([
+      {
+        method: 'get',
+        outcome: 'tool-error',
+        errorCode: 'provider-rejected',
+        providerStatus: 422,
+      },
+    ]);
   });
 });
 

package/src/presentation/routes/agent-tools-gateway/mcp-server.ts

@@ -6,7 +6,13 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import {reportError} from '@shipfox/node-error-monitoring';
 import {logger} from '@shipfox/node-opentelemetry';
-import {INVALID_METHOD_LABEL, type IntegrationToolCallRecorder, NO_METHOD_LABEL} from './audit.js';
+import {normalizeIntegrationAgentToolCallErrorCode} from '#metrics/index.js';
+import {
+  INVALID_METHOD_LABEL,
+  type IntegrationAgentToolCallErrorCode,
+  type IntegrationToolCallRecorder,
+  NO_METHOD_LABEL,
+} from './audit.js';
 import type {
   AuthorizedIntegrationTool,
   AuthorizedIntegrationToolMap,
@@ -61,6 +67,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: request.params.arguments ?? {},
         method: NO_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError(`Unknown integration tool: ${request.params.name}`);
     }
@@ -72,6 +79,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method: NO_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError('Tool arguments must be an object');
     }
@@ -83,6 +91,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method: INVALID_METHOD_LABEL,
         outcome: 'invalid-request',
+        errorCode: 'invalid-request',
       });
       return toolError(methodValidation.message);
     }
@@ -99,6 +108,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method,
         outcome: result.isError === true ? 'tool-error' : 'success',
+        ...toolCallErrorDetails(result),
       });
       return result;
     } catch (error) {
@@ -107,6 +117,7 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
         arguments: args,
         method,
         outcome: 'exception',
+        errorCode: 'unknown',
       });
       throw error;
     }
@@ -115,6 +126,23 @@ export function buildAgentToolsMcpServer(params: BuildAgentToolsMcpServerParams)
   return server;
 }
 
+function toolCallErrorDetails(result: CallToolResult): {
+  errorCode: IntegrationAgentToolCallErrorCode | 'none';
+  providerStatus?: number | undefined;
+} {
+  if (result.isError !== true) return {errorCode: 'none'};
+
+  const structuredContent = isRecord(result.structuredContent)
+    ? result.structuredContent
+    : undefined;
+  const providerStatus = statusCode(structuredContent?.status);
+
+  return {
+    errorCode: normalizeIntegrationAgentToolCallErrorCode(structuredContent?.code),
+    ...(providerStatus === undefined ? {} : {providerStatus}),
+  };
+}
+
 function recordToolCall(
   recordCall: IntegrationToolCallRecorder | undefined,
   record: Parameters<IntegrationToolCallRecorder>[0],
@@ -157,3 +185,9 @@ function toolError(message: string): CallToolResult {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+
+function statusCode(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599
+    ? value
+    : undefined;
+}