@shipfox/api-integration-core 2.0.0

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

@@ -0,0 +1,371 @@
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type {Transport} from '@modelcontextprotocol/sdk/shared/transport.js';
+import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js';
+import {
+  AUTH_LEASED_JOB,
+  type LeasedJobContext,
+  setLeasedJobContext,
+} from '@shipfox/api-auth-context';
+import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import {
+  agentStepConfig,
+  catalogTool,
+  connection,
+  leaseContext,
+  materializedIntegration,
+  registryWithAgentTools,
+} from '#test/agent-tools-gateway-helpers.js';
+import {createAgentToolsGatewayRoutes} from './index.js';
+
+let leases = new Map<string, LeasedJobContext>();
+
+const fakeLeaseAuth: AuthMethod = {
+  name: AUTH_LEASED_JOB,
+  authenticate: (request: FastifyRequest) => {
+    const authorization = request.headers.authorization;
+    const token =
+      typeof authorization === 'string' && authorization.startsWith('Bearer ')
+        ? authorization.slice('Bearer '.length)
+        : null;
+    const lease = token ? leases.get(token) : undefined;
+    if (!lease) {
+      throw new ClientError('Invalid job lease token', 'unauthorized', {status: 401});
+    }
+
+    setLeasedJobContext(request, lease);
+    return Promise.resolve();
+  },
+};
+
+describe('agent tools gateway route', () => {
+  beforeEach(async () => {
+    await closeApp();
+    leases = new Map();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('requires lease auth before resolving tools', async () => {
+    const app = await createGatewayApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runs/jobs/current/integration-tools/mcp',
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('returns a normal HTTP error for pre-hijack resolution failures', async () => {
+    const lease = leaseContext({currentStepId: undefined, currentStepAttempt: undefined});
+    leases.set('lease-without-step', lease);
+    const app = await createGatewayApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/runs/jobs/current/integration-tools/mcp',
+      headers: {authorization: 'Bearer lease-without-step'},
+      payload: {},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('lease-missing-step');
+  });
+
+  it('serves MCP over stateless Streamable HTTP after resolving server-side state', async () => {
+    const lease = leaseContext({workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    const calls: unknown[] = [];
+    const sessionTools: unknown[] = [];
+    const close = vi.fn();
+    leases.set('valid-lease', lease);
+    const app = await createGatewayApp({
+      registry: registryWithAgentTools([catalogTool()], {
+        onOpenSession: (input) => sessionTools.push(...input.tools),
+        onCall: (call) => calls.push(call),
+        onClose: close,
+      }),
+      loadLeasedAgentStep: async () => ({
+        workspaceId: lease.workspaceId,
+        step: {type: 'agent', config: agentStepConfig([integration])},
+      }),
+      getIntegrationConnectionById: async () =>
+        connection({
+          id: integration.connectionId,
+          workspaceId: lease.workspaceId,
+          slug: integration.connectionSlug,
+        }),
+    });
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(
+      new URL('/runs/jobs/current/integration-tools/mcp', address),
+      {
+        requestInit: {
+          headers: {authorization: 'Bearer valid-lease'},
+        },
+      },
+    );
+
+    await client.connect(transport as unknown as Transport);
+    const tools = await client.listTools();
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(tools.tools.map((tool) => tool.name)).toEqual(['github_main__issue_read']);
+    expect(result.isError).not.toBe(true);
+    expect(result.structuredContent).toMatchObject({
+      status: 'dispatched',
+      provider: 'github',
+      connection_id: 'connection-1',
+      tool_id: 'issue_read',
+      method: 'get',
+    });
+    expect(calls).toEqual([
+      {
+        toolId: 'issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+    ]);
+    expect(sessionTools).toMatchObject([
+      {
+        methods: [
+          {id: 'get', description: 'Get one issue.'},
+          {id: 'get_comments', description: 'Get issue comments.'},
+        ],
+      },
+    ]);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns bounded MCP errors when provider dispatch times out', async () => {
+    const lease = leaseContext({workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    const timeout = new Error('request timeout after 30s');
+    timeout.name = 'TimeoutError';
+    const close = vi.fn();
+    leases.set('timeout-lease', lease);
+    const app = await createGatewayApp({
+      registry: registryWithAgentTools([catalogTool()], {callError: timeout, onClose: close}),
+      loadLeasedAgentStep: async () => ({
+        workspaceId: lease.workspaceId,
+        step: {type: 'agent', config: agentStepConfig([integration])},
+      }),
+      getIntegrationConnectionById: async () =>
+        connection({
+          id: integration.connectionId,
+          workspaceId: lease.workspaceId,
+          slug: integration.connectionSlug,
+        }),
+    });
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(
+      new URL('/runs/jobs/current/integration-tools/mcp', address),
+      {
+        requestInit: {
+          headers: {authorization: 'Bearer timeout-lease'},
+        },
+      },
+    );
+
+    await client.connect(transport as unknown as Transport);
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Integration provider timed out'}],
+      structuredContent: {code: 'provider-timeout'},
+    });
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('classifies the MCP SDK request timeout shape as a provider timeout', async () => {
+    const lease = leaseContext({workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    const timeout = new Error('MCP error -32001: Request timed out');
+    timeout.name = 'McpError';
+    leases.set('mcp-timeout-lease', lease);
+    const app = await createGatewayApp({
+      registry: registryWithAgentTools([catalogTool()], {callError: timeout}),
+      loadLeasedAgentStep: async () => ({
+        workspaceId: lease.workspaceId,
+        step: {type: 'agent', config: agentStepConfig([integration])},
+      }),
+      getIntegrationConnectionById: async () =>
+        connection({
+          id: integration.connectionId,
+          workspaceId: lease.workspaceId,
+          slug: integration.connectionSlug,
+        }),
+    });
+
+    const result = await callIssueReadTool(app, 'mcp-timeout-lease');
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Integration provider timed out'}],
+      structuredContent: {code: 'provider-timeout'},
+    });
+  });
+
+  it('returns bounded MCP errors when provider dispatch fails', async () => {
+    const lease = leaseContext({workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    leases.set('provider-error-lease', lease);
+    const app = await createGatewayApp({
+      registry: registryWithAgentTools([catalogTool()], {
+        callError: new Error('remote provider leaked implementation detail'),
+      }),
+      loadLeasedAgentStep: async () => ({
+        workspaceId: lease.workspaceId,
+        step: {type: 'agent', config: agentStepConfig([integration])},
+      }),
+      getIntegrationConnectionById: async () =>
+        connection({
+          id: integration.connectionId,
+          workspaceId: lease.workspaceId,
+          slug: integration.connectionSlug,
+        }),
+    });
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(
+      new URL('/runs/jobs/current/integration-tools/mcp', address),
+      {
+        requestInit: {
+          headers: {authorization: 'Bearer provider-error-lease'},
+        },
+      },
+    );
+
+    await client.connect(transport as unknown as Transport);
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Integration provider call failed'}],
+      structuredContent: {code: 'provider-unavailable'},
+    });
+  });
+
+  it('returns bounded MCP errors when provider credentials are unavailable', async () => {
+    const lease = leaseContext({workspaceId: 'workspace-1'});
+    const integration = materializedIntegration({connectionId: 'connection-1'});
+    const tokenError = new Error('missing token for connection-1');
+    tokenError.name = 'LinearAccessTokenMissingError';
+    leases.set('credential-error-lease', lease);
+    const app = await createGatewayApp({
+      registry: registryWithAgentTools([catalogTool()], {openSessionError: tokenError}),
+      loadLeasedAgentStep: async () => ({
+        workspaceId: lease.workspaceId,
+        step: {type: 'agent', config: agentStepConfig([integration])},
+      }),
+      getIntegrationConnectionById: async () =>
+        connection({
+          id: integration.connectionId,
+          workspaceId: lease.workspaceId,
+          slug: integration.connectionSlug,
+        }),
+    });
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(
+      new URL('/runs/jobs/current/integration-tools/mcp', address),
+      {
+        requestInit: {
+          headers: {authorization: 'Bearer credential-error-lease'},
+        },
+      },
+    );
+
+    await client.connect(transport as unknown as Transport);
+    const result = await client.callTool(
+      {
+        name: 'github_main__issue_read',
+        arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+      },
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Integration provider credentials are unavailable'}],
+      structuredContent: {code: 'credentials-unavailable'},
+    });
+  });
+});
+
+async function createGatewayApp(
+  overrides: Partial<Parameters<typeof createAgentToolsGatewayRoutes>[0]> = {},
+): Promise<FastifyInstance> {
+  const app = await createApp({
+    auth: [fakeLeaseAuth],
+    routes: [
+      createAgentToolsGatewayRoutes({
+        registry: registryWithAgentTools(),
+        getIntegrationConnectionById: async () =>
+          connection({workspaceId: 'workspace-1', id: 'connection-1'}),
+        loadLeasedAgentStep: async () => ({
+          workspaceId: 'workspace-1',
+          step: {type: 'agent', config: agentStepConfig()},
+        }),
+        ...overrides,
+      }),
+    ],
+    swagger: false,
+  });
+  await app.ready();
+  return app;
+}
+
+async function callIssueReadTool(app: FastifyInstance, leaseToken: string) {
+  const address = await app.listen({port: 0, host: '127.0.0.1'});
+  const client = new Client({name: 'test-http-client', version: '0.0.0'});
+  const transport = new StreamableHTTPClientTransport(
+    new URL('/runs/jobs/current/integration-tools/mcp', address),
+    {
+      requestInit: {
+        headers: {authorization: `Bearer ${leaseToken}`},
+      },
+    },
+  );
+
+  await client.connect(transport as unknown as Transport);
+  const result = await client.callTool(
+    {
+      name: 'github_main__issue_read',
+      arguments: {method: 'get', owner: 'shipfox', repo: 'platform', issue_number: 1},
+    },
+    CallToolResultSchema,
+  );
+  await client.close();
+
+  return result;
+}

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

@@ -0,0 +1,86 @@
+import {
+  connection,
+  leaseContext,
+  materializedIntegration,
+  materializedTool,
+} from '#test/agent-tools-gateway-helpers.js';
+import {createIntegrationToolCallRecorder, summarizeIntegrationToolArguments} from './audit.js';
+
+describe('integration tool call audit', () => {
+  it('records bounded metric labels and structured audit context', () => {
+    const recordMetric = vi.fn();
+    const logInfo = vi.fn();
+    const lease = leaseContext({
+      jobId: 'job-1',
+      jobExecutionId: 'execution-1',
+      workflowRunId: 'run-1',
+      workflowRunAttemptId: 'attempt-1',
+      workspaceId: 'workspace-1',
+      currentStepId: 'step-1',
+      currentStepAttempt: 2,
+    });
+    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: 'platform',
+        owner: 'shipfox',
+        token: 'must-not-appear',
+      },
+      method: 'get',
+      outcome: 'success',
+    });
+
+    expect(recordMetric).toHaveBeenCalledWith({
+      provider: 'github',
+      tool: 'issue_read',
+      method: 'get',
+      outcome: 'success',
+    });
+    expect(logInfo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jobId: 'job-1',
+        jobExecutionId: 'execution-1',
+        workflowRunId: 'run-1',
+        workflowRunAttemptId: 'attempt-1',
+        workspaceId: 'workspace-1',
+        currentStepId: 'step-1',
+        currentStepAttempt: 2,
+        connectionId: 'connection-1',
+        provider: 'github',
+        toolId: 'issue_read',
+        method: 'get',
+        outcome: 'success',
+        argumentSummary: {
+          keys: ['owner', 'repo', 'token'],
+          serializedSizeBytes: expect.any(Number),
+        },
+      }),
+      'integration tool call audited',
+    );
+    expect(JSON.stringify(logInfo.mock.calls)).not.toContain('must-not-appear');
+  });
+
+  it('summarizes arguments without values', () => {
+    const summary = summarizeIntegrationToolArguments({z: 'secret', a: 1});
+
+    expect(summary).toEqual({
+      keys: ['a', 'z'],
+      serializedSizeBytes: 20,
+    });
+  });
+});

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

@@ -0,0 +1,90 @@
+import type {LeasedJobContext} from '@shipfox/api-auth-context';
+import {logger} from '@shipfox/node-opentelemetry';
+import {
+  type IntegrationAgentToolCallOutcome,
+  recordIntegrationAgentToolCall,
+} from '#metrics/index.js';
+import type {AuthorizedIntegrationTool} from './resolve-authorized-tools.js';
+
+export const UNKNOWN_TOOL_LABEL = 'unknown';
+export const NO_METHOD_LABEL = 'none';
+export const INVALID_METHOD_LABEL = 'invalid';
+
+export interface IntegrationToolArgumentSummary {
+  keys: string[];
+  serializedSizeBytes: number;
+}
+
+export interface IntegrationToolCallAuditRecord {
+  authorizedTool?: AuthorizedIntegrationTool | undefined;
+  arguments: unknown;
+  method: string;
+  outcome: IntegrationAgentToolCallOutcome;
+}
+
+export type IntegrationToolCallRecorder = (record: IntegrationToolCallAuditRecord) => void;
+
+export interface CreateIntegrationToolCallRecorderOptions {
+  recordMetric?: typeof recordIntegrationAgentToolCall | undefined;
+  logInfo?:
+    | ((context: Record<string, unknown>, message: 'integration tool call audited') => void)
+    | undefined;
+}
+
+export function createIntegrationToolCallRecorder(
+  lease: LeasedJobContext,
+  options: CreateIntegrationToolCallRecorderOptions = {},
+): IntegrationToolCallRecorder {
+  const recordMetric = options.recordMetric ?? recordIntegrationAgentToolCall;
+  const logInfo = options.logInfo ?? ((context, message) => logger().info(context, message));
+
+  return (record) => {
+    const provider = record.authorizedTool?.integration.provider ?? UNKNOWN_TOOL_LABEL;
+    const toolId = record.authorizedTool?.tool.id ?? UNKNOWN_TOOL_LABEL;
+
+    recordMetric({
+      provider,
+      tool: toolId,
+      method: record.method,
+      outcome: record.outcome,
+    });
+
+    logInfo(
+      {
+        jobId: lease.jobId,
+        jobExecutionId: lease.jobExecutionId,
+        workflowRunId: lease.workflowRunId,
+        workflowRunAttemptId: lease.workflowRunAttemptId,
+        workspaceId: lease.workspaceId,
+        currentStepId: lease.currentStepId,
+        currentStepAttempt: lease.currentStepAttempt,
+        connectionId: record.authorizedTool?.connection.id,
+        provider,
+        toolId,
+        method: record.method,
+        outcome: record.outcome,
+        argumentSummary: summarizeIntegrationToolArguments(record.arguments),
+      },
+      'integration tool call audited',
+    );
+  };
+}
+
+export function summarizeIntegrationToolArguments(value: unknown): IntegrationToolArgumentSummary {
+  return {
+    keys: isRecord(value) ? Object.keys(value).sort() : [],
+    serializedSizeBytes: serializedSize(value),
+  };
+}
+
+function serializedSize(value: unknown): number {
+  try {
+    return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+  } catch {
+    return 0;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,139 @@
+import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js';
+import {IntegrationProviderError} from '#core/errors.js';
+import type {
+  AgentToolCatalogEntry,
+  AgentToolCatalogMethod,
+  AgentToolSession,
+  AgentToolsProvider,
+} from '#core/providers/agent-tools.js';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import type {IntegrationToolDispatcher, IntegrationToolDispatchInput} from './mcp-server.js';
+
+export interface CreateIntegrationToolDispatcherParams {
+  registry: IntegrationProviderRegistry;
+}
+
+const timeoutErrorPattern = /timed?\s*out|timeout/i;
+const credentialErrorNamePattern = /Token|Credential|Secret|AccessToken/;
+
+export function createIntegrationToolDispatcher(
+  params: CreateIntegrationToolDispatcherParams,
+): IntegrationToolDispatcher {
+  return (input) => dispatchIntegrationToolCall({...input, registry: params.registry});
+}
+
+async function dispatchIntegrationToolCall(
+  input: IntegrationToolDispatchInput & {registry: IntegrationProviderRegistry},
+): Promise<CallToolResult> {
+  let session: AgentToolSession<CallToolResult> | undefined;
+
+  try {
+    const adapter = input.registry.getAdapter(
+      input.authorizedTool.integration.provider,
+      'agent_tools',
+    ) as AgentToolsProvider<
+      typeof input.authorizedTool.connection,
+      unknown,
+      typeof input.authorizedTool.integration,
+      CallToolResult
+    >;
+    session = await adapter.openSession({
+      connection: input.authorizedTool.connection,
+      tools: [agentToolCatalogEntry(input)],
+      scope: input.authorizedTool.integration,
+    });
+
+    return await session.call({
+      toolId: input.authorizedTool.tool.id,
+      arguments: input.arguments,
+    });
+  } catch (error) {
+    return toolError(errorResult(error));
+  } finally {
+    await closeSession(session);
+  }
+}
+
+function agentToolCatalogEntry(input: IntegrationToolDispatchInput): AgentToolCatalogEntry {
+  const {tool, description, inputSchema, outputSchema} = input.authorizedTool;
+  return {
+    id: tool.id,
+    description,
+    sensitivity: tool.sensitivity,
+    sensitive: tool.sensitive,
+    requiredScope: tool.requiredScope,
+    inputSchema,
+    ...(outputSchema === undefined ? {} : {outputSchema}),
+    ...(tool.methods === undefined
+      ? {}
+      : {
+          methods: tool.methods.map(
+            (method): AgentToolCatalogMethod => ({
+              id: method.id,
+              description: method.description ?? method.token,
+              sensitivity: method.sensitivity,
+              sensitive: method.sensitive,
+              requiredScope: method.requiredScope,
+            }),
+          ),
+        }),
+  };
+}
+
+async function closeSession(session: {close?(): Promise<void>} | undefined): Promise<void> {
+  try {
+    await session?.close?.();
+  } catch {
+    // Cleanup must not mask the tool result returned to the runner.
+  }
+}
+
+function errorResult(error: unknown): {code: string; message: string} {
+  if (error instanceof IntegrationProviderError) {
+    return {
+      code: error.reason,
+      message: `Integration provider error: ${error.reason}`,
+    };
+  }
+
+  if (isTimeoutError(error)) {
+    return {
+      code: 'provider-timeout',
+      message: 'Integration provider timed out',
+    };
+  }
+
+  if (isCredentialError(error)) {
+    return {
+      code: 'credentials-unavailable',
+      message: 'Integration provider credentials are unavailable',
+    };
+  }
+
+  return {
+    code: 'provider-unavailable',
+    message: 'Integration provider call failed',
+  };
+}
+
+function isTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return (
+    error.name === 'AbortError' ||
+    timeoutErrorPattern.test(error.name) ||
+    timeoutErrorPattern.test(error.message)
+  );
+}
+
+function isCredentialError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return credentialErrorNamePattern.test(error.name);
+}
+
+function toolError(params: {code: string; message: string}): CallToolResult {
+  return {
+    isError: true,
+    content: [{type: 'text', text: params.message}],
+    structuredContent: {code: params.code},
+  };
+}