@truefoundry/trueforge-core 0.0.0 → 0.1.0-rc.0

package/dist/core/mcp/RemoteMCP.d.ts

@@ -0,0 +1,67 @@
+import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { Logger } from 'winston';
+import type { InternalToolCallInfo } from '../llm/LLMTypes';
+import type { AgentTracing } from '../tracing/AgentTracing';
+import { type AuthRequiredResponse, type CallToolResolvedResponse, type ListToolsResolvedResponse, type MCPAuthRequired, type ToolSource } from './IMCPServer';
+import { type RemoteMcpTransportType } from './remoteMcpClient';
+/** What a headers resolver returns: the headers to send, or a signal that auth is required. */
+export type ResolveHeadersResult = {
+    headers: Record<string, string>;
+} | {
+    authRequired: MCPAuthRequired;
+};
+/** Static headers, or a resolver (invoked at connect) returning headers or signalling auth-required. */
+export type RemoteMcpHeaders = Record<string, string> | (() => Promise<ResolveHeadersResult>);
+/**
+ * Connection/session half of a remote MCP server: owns the transport (connects itself from `url` +
+ * `headers`), session id, raw tool cache, connect single-flight and session-expiry retry. Policy-free
+ * — a per-agent {@link ToolSet} layers policy.
+ */
+export declare class RemoteMCP implements ToolSource {
+    readonly name: string;
+    readonly id: string;
+    readonly description?: string | undefined;
+    private readonly url;
+    private readonly headers;
+    private readonly signal;
+    private readonly logger;
+    private readonly tracing;
+    private readonly requestTimeoutMs;
+    private readonly connectTimeoutMs;
+    private readonly traceUrl;
+    private _connection?;
+    private isConnected;
+    private connectPromise;
+    private sessionId;
+    private resolvedTransportType?;
+    private cachedTools?;
+    constructor(params: {
+        name: string;
+        id: string;
+        description?: string | undefined;
+        url: string;
+        headers: RemoteMcpHeaders;
+        logger: Logger;
+        tracing?: AgentTracing | undefined;
+        sessionId?: string | undefined;
+        transportType?: RemoteMcpTransportType | undefined;
+        requestTimeoutMs: number;
+        connectTimeoutMs: number;
+        signal: AbortSignal;
+    });
+    getSessionId(): string | undefined;
+    private get connection();
+    private resetConnection;
+    private closeAndClearConnection;
+    private resolveHeaders;
+    private executeWithSessionRetry;
+    private connectAndRun;
+    private loadTools;
+    /** Unfiltered tool list (no policy). The per-agent wrapper applies selectors on top. */
+    listTools(): Promise<ListToolsResolvedResponse | AuthRequiredResponse>;
+    callTool(params: CallToolRequest['params']): Promise<CallToolResolvedResponse | AuthRequiredResponse>;
+    toolCallInfo(params: CallToolRequest['params'], _resolveUnderlyingTool?: boolean): Promise<InternalToolCallInfo>;
+    private connectIfNeeded;
+    private toConnectError;
+}
+//# sourceMappingURL=RemoteMCP.d.ts.map

package/dist/core/mcp/RemoteMCP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteMCP.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/RemoteMCP.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp/RemoteMCP.js

@@ -0,0 +1,244 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/mcp/RemoteMCP.ts
+var RemoteMCP_exports = {};
+__export(RemoteMCP_exports, {
+  RemoteMCP: () => RemoteMCP
+});
+module.exports = __toCommonJS(RemoteMCP_exports);
+var import_errors = require("../errors.js");
+var import_NoopAgentTracing = require("../tracing/NoopAgentTracing.js");
+var import_IMCPServer = require("./IMCPServer.js");
+var import_pagination = require("./pagination.js");
+var import_remoteMcpClient = require("./remoteMcpClient.js");
+function redactUrlForTrace(url) {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host}${u.pathname}`;
+  } catch {
+    return "";
+  }
+}
+var RemoteMCP = class {
+  name;
+  id;
+  description;
+  url;
+  headers;
+  signal;
+  logger;
+  tracing;
+  requestTimeoutMs;
+  connectTimeoutMs;
+  // Redacted display url for trace spans (derived from url; unused when tracing is a no-op).
+  traceUrl;
+  _connection;
+  isConnected = false;
+  connectPromise;
+  // undefined = never connected, string = stateful session id, null = stateless/SSE.
+  sessionId;
+  resolvedTransportType;
+  cachedTools;
+  constructor(params) {
+    this.name = params.name;
+    this.id = params.id;
+    this.description = params.description;
+    this.url = params.url;
+    this.headers = params.headers;
+    this.signal = params.signal;
+    this.sessionId = params.sessionId;
+    this.resolvedTransportType = params.transportType;
+    this.requestTimeoutMs = params.requestTimeoutMs;
+    this.connectTimeoutMs = params.connectTimeoutMs;
+    this.logger = params.logger;
+    this.tracing = params.tracing ?? import_NoopAgentTracing.NOOP_AGENT_TRACING;
+    this.traceUrl = redactUrlForTrace(params.url);
+  }
+  getSessionId() {
+    return this.sessionId ?? void 0;
+  }
+  get connection() {
+    if (!this._connection) {
+      throw new Error(`Remote MCP '${this.name}' not connected - connectIfNeeded() must run first`);
+    }
+    return this._connection;
+  }
+  async resetConnection() {
+    this.isConnected = false;
+    this.sessionId = void 0;
+    this.cachedTools = void 0;
+    this.connectPromise = void 0;
+    await this.closeAndClearConnection();
+  }
+  async closeAndClearConnection() {
+    await this._connection?.close().catch(() => {
+    });
+    this._connection = void 0;
+  }
+  async resolveHeaders() {
+    if (typeof this.headers !== "function") return { headers: this.headers };
+    return await this.headers();
+  }
+  async executeWithSessionRetry(operation) {
+    const headersResult = await this.resolveHeaders();
+    if ("authRequired" in headersResult) return { authRequired: headersResult.authRequired };
+    return this.connectAndRun(headersResult.headers, operation, true);
+  }
+  async connectAndRun(headers, operation, canRetry) {
+    try {
+      const initInfo = await this.connectIfNeeded(headers);
+      return { result: await operation(), wasInitialized: initInfo };
+    } catch (error) {
+      if (canRetry && (0, import_remoteMcpClient.isSessionExpiredError)(error)) {
+        this.logger.info(`Session expired for remote MCP ${this.name}, reinitializing...`);
+        await this.resetConnection();
+        return this.connectAndRun(headers, operation, false);
+      }
+      throw error;
+    }
+  }
+  async loadTools() {
+    return this.tracing.withRemoteMcpToolSpan(
+      { method: "tools/list", serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },
+      async (span) => {
+        const tools = await (0, import_pagination.paginateWithCursorGuard)(
+          async (cursor) => {
+            const page = await this.connection.listTools(cursor);
+            return { items: page.tools, nextCursor: page.nextCursor };
+          },
+          this.name,
+          this.logger
+        );
+        this.cachedTools = tools.map((t) => ({ ...t, preload: true }));
+        span.setNumberOfTools(this.cachedTools.length);
+        return { tools: this.cachedTools };
+      }
+    );
+  }
+  /** Unfiltered tool list (no policy). The per-agent wrapper applies selectors on top. */
+  async listTools() {
+    if (this.cachedTools) {
+      return { result: { tools: this.cachedTools }, wasInitialized: void 0 };
+    }
+    const response = await this.executeWithSessionRetry(() => this.loadTools());
+    if ("authRequired" in response) return response;
+    return { result: { tools: response.result.tools }, wasInitialized: response.wasInitialized };
+  }
+  async callTool(params) {
+    const response = await this.executeWithSessionRetry(
+      () => this.tracing.withRemoteMcpToolSpan(
+        {
+          method: "tools/call",
+          serverName: this.name,
+          serverId: this.id,
+          serverUrl: this.traceUrl,
+          toolName: params.name,
+          input: JSON.stringify(params.arguments),
+          enabled: true
+        },
+        async (span) => {
+          const result = await this.connection.callTool(params);
+          span.setOutput(JSON.stringify(result));
+          return result;
+        }
+      )
+    );
+    if ("authRequired" in response) return response;
+    return { result: response.result, wasInitialized: response.wasInitialized };
+  }
+  toolCallInfo(params, _resolveUnderlyingTool) {
+    void _resolveUnderlyingTool;
+    return Promise.resolve({
+      type: "mcp",
+      original_tool_name: params.name,
+      mcp_server_id: this.id,
+      mcp_server_name: this.name,
+      is_approval_required: false
+    });
+  }
+  async connectIfNeeded(headers) {
+    if (this.isConnected) return void 0;
+    if (this.connectPromise) {
+      await this.connectPromise;
+      return void 0;
+    }
+    const existingSessionId = this.sessionId;
+    this.connectPromise = (async () => {
+      let connection;
+      try {
+        await this.closeAndClearConnection();
+        connection = await this.tracing.withRemoteMcpToolSpan(
+          { method: "initialize", serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },
+          async (span) => {
+            const conn = await (0, import_remoteMcpClient.connectRemoteMcp)({
+              url: this.url,
+              headers,
+              sessionId: this.sessionId ?? void 0,
+              // Hint from a prior connect
+              knownTransportType: this.resolvedTransportType,
+              requestTimeoutMs: this.requestTimeoutMs,
+              connectTimeoutMs: this.connectTimeoutMs,
+              signal: this.signal,
+              onClose: () => {
+                this.isConnected = false;
+              },
+              onError: (error) => {
+                this.logger.error(`Error on remote MCP transport ${this.name}`, { error });
+              }
+            });
+            span.setOutput(JSON.stringify({ transport: conn.transportType, stateful: conn.sessionId !== null }));
+            return conn;
+          }
+        );
+      } catch (error) {
+        await this.closeAndClearConnection();
+        throw this.toConnectError(error);
+      }
+      this._connection = connection;
+      this.resolvedTransportType = connection.transportType;
+      this.isConnected = true;
+      this.sessionId = connection.sessionId;
+      if (existingSessionId === this.sessionId) {
+        return void 0;
+      }
+      return {
+        name: this.name,
+        id: this.id,
+        session_id: this.sessionId ?? void 0,
+        transport_type: this.resolvedTransportType
+      };
+    })().finally(() => {
+      this.connectPromise = void 0;
+    });
+    return this.connectPromise;
+  }
+  toConnectError(error) {
+    const statusCode = error instanceof import_errors.McpConnectionError ? error.statusCode : 502;
+    const message = error instanceof Error ? error.message : String(error);
+    return new import_errors.McpConnectionError(`Failed to connect to remote MCP server '${this.name}': ${message}`, statusCode, {
+      cause: error
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RemoteMCP
+});
+//# sourceMappingURL=RemoteMCP.js.map

package/dist/core/mcp/RemoteMCP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/mcp/RemoteMCP.ts"],"sourcesContent":["import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';\nimport type { Logger } from 'winston';\nimport { McpConnectionError } from '../errors';\nimport type { MCPServerInitInfo } from '../events/schema';\nimport type { InternalToolCallInfo } from '../llm/LLMTypes';\nimport type { AgentTracing } from '../tracing/AgentTracing';\nimport { NOOP_AGENT_TRACING } from '../tracing/NoopAgentTracing';\nimport {\n  type AgentToolSchema,\n  type AuthRequiredResponse,\n  type CallToolResolvedResponse,\n  type ListToolsResolvedResponse,\n  type MCPAuthRequired,\n  type ToolSource,\n} from './IMCPServer';\nimport { paginateWithCursorGuard } from './pagination';\nimport {\n  connectRemoteMcp,\n  isSessionExpiredError,\n  type RemoteMcpConnection,\n  type RemoteMcpTransportType,\n} from './remoteMcpClient';\n\n/** Redacted url for trace spans: scheme + host + path only, so userinfo/query secrets never leak. */\nfunction redactUrlForTrace(url: string): string {\n  try {\n    const u = new URL(url);\n    return `${u.protocol}//${u.host}${u.pathname}`;\n  } catch {\n    return '';\n  }\n}\n\n/** What a headers resolver returns: the headers to send, or a signal that auth is required. */\nexport type ResolveHeadersResult = { headers: Record<string, string> } | { authRequired: MCPAuthRequired };\n\n/** Static headers, or a resolver (invoked at connect) returning headers or signalling auth-required. */\nexport type RemoteMcpHeaders = Record<string, string> | (() => Promise<ResolveHeadersResult>);\n\ntype ExecuteResult<T> = { result: T; wasInitialized: MCPServerInitInfo | undefined } | AuthRequiredResponse;\n\n/**\n * Connection/session half of a remote MCP server: owns the transport (connects itself from `url` +\n * `headers`), session id, raw tool cache, connect single-flight and session-expiry retry. Policy-free\n * — a per-agent {@link ToolSet} layers policy.\n */\nexport class RemoteMCP implements ToolSource {\n  readonly name: string;\n  readonly id: string;\n  readonly description?: string | undefined;\n\n  private readonly url: string;\n  private readonly headers: RemoteMcpHeaders;\n  private readonly signal: AbortSignal;\n  private readonly logger: Logger;\n  private readonly tracing: AgentTracing;\n  private readonly requestTimeoutMs: number;\n  private readonly connectTimeoutMs: number;\n  // Redacted display url for trace spans (derived from url; unused when tracing is a no-op).\n  private readonly traceUrl: string;\n\n  private _connection?: RemoteMcpConnection | undefined;\n  private isConnected = false;\n  private connectPromise: Promise<MCPServerInitInfo | undefined> | undefined;\n  // undefined = never connected, string = stateful session id, null = stateless/SSE.\n  private sessionId: string | null | undefined;\n  private resolvedTransportType?: RemoteMcpTransportType | undefined;\n  private cachedTools?: AgentToolSchema[] | undefined;\n\n  constructor(params: {\n    name: string;\n    id: string;\n    description?: string | undefined;\n    url: string;\n    headers: RemoteMcpHeaders;\n    logger: Logger;\n    tracing?: AgentTracing | undefined;\n    sessionId?: string | undefined;\n    transportType?: RemoteMcpTransportType | undefined;\n    requestTimeoutMs: number;\n    connectTimeoutMs: number;\n    signal: AbortSignal;\n  }) {\n    this.name = params.name;\n    this.id = params.id;\n    this.description = params.description;\n    this.url = params.url;\n    this.headers = params.headers;\n    this.signal = params.signal;\n    this.sessionId = params.sessionId;\n    this.resolvedTransportType = params.transportType;\n    this.requestTimeoutMs = params.requestTimeoutMs;\n    this.connectTimeoutMs = params.connectTimeoutMs;\n    this.logger = params.logger;\n    this.tracing = params.tracing ?? NOOP_AGENT_TRACING;\n    this.traceUrl = redactUrlForTrace(params.url);\n  }\n\n  getSessionId(): string | undefined {\n    return this.sessionId ?? undefined;\n  }\n\n  private get connection(): RemoteMcpConnection {\n    if (!this._connection) {\n      throw new Error(`Remote MCP '${this.name}' not connected - connectIfNeeded() must run first`);\n    }\n    return this._connection;\n  }\n\n  private async resetConnection(): Promise<void> {\n    this.isConnected = false;\n    this.sessionId = undefined;\n    this.cachedTools = undefined;\n    this.connectPromise = undefined;\n    await this.closeAndClearConnection();\n  }\n\n  private async closeAndClearConnection(): Promise<void> {\n    await this._connection?.close().catch(() => {\n      /* no-op */\n    });\n    this._connection = undefined;\n  }\n\n  private async resolveHeaders(): Promise<ResolveHeadersResult> {\n    if (typeof this.headers !== 'function') return { headers: this.headers };\n    return await this.headers();\n  }\n\n  private async executeWithSessionRetry<T>(operation: () => Promise<T>): Promise<ExecuteResult<T>> {\n    // Auth is re-checked on every operation, not only on the first connect: a registered server's OAuth\n    // can be revoked or expire mid-request, and callers must get authRequired rather than a generic\n    // upstream failure. When already connected the resolved headers are unused (connect is skipped).\n    const headersResult = await this.resolveHeaders();\n    if ('authRequired' in headersResult) return { authRequired: headersResult.authRequired };\n    return this.connectAndRun(headersResult.headers, operation, true);\n  }\n\n  private async connectAndRun<T>(\n    headers: Record<string, string>,\n    operation: () => Promise<T>,\n    canRetry: boolean,\n  ): Promise<ExecuteResult<T>> {\n    try {\n      const initInfo = await this.connectIfNeeded(headers);\n      return { result: await operation(), wasInitialized: initInfo };\n    } catch (error) {\n      if (canRetry && isSessionExpiredError(error)) {\n        this.logger.info(`Session expired for remote MCP ${this.name}, reinitializing...`);\n        await this.resetConnection();\n        return this.connectAndRun(headers, operation, false);\n      }\n      throw error;\n    }\n  }\n\n  private async loadTools(): Promise<{ tools: AgentToolSchema[] }> {\n    return this.tracing.withRemoteMcpToolSpan(\n      { method: 'tools/list', serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },\n      async span => {\n        const tools = await paginateWithCursorGuard(\n          async cursor => {\n            const page = await this.connection.listTools(cursor);\n            return { items: page.tools, nextCursor: page.nextCursor };\n          },\n          this.name,\n          this.logger,\n        );\n        this.cachedTools = tools.map(t => ({ ...t, preload: true }));\n        span.setNumberOfTools(this.cachedTools.length);\n        return { tools: this.cachedTools };\n      },\n    );\n  }\n\n  /** Unfiltered tool list (no policy). The per-agent wrapper applies selectors on top. */\n  async listTools(): Promise<ListToolsResolvedResponse | AuthRequiredResponse> {\n    if (this.cachedTools) {\n      return { result: { tools: this.cachedTools }, wasInitialized: undefined };\n    }\n    const response = await this.executeWithSessionRetry(() => this.loadTools());\n    if ('authRequired' in response) return response;\n    return { result: { tools: response.result.tools }, wasInitialized: response.wasInitialized };\n  }\n\n  async callTool(params: CallToolRequest['params']): Promise<CallToolResolvedResponse | AuthRequiredResponse> {\n    const response = await this.executeWithSessionRetry(() =>\n      this.tracing.withRemoteMcpToolSpan(\n        {\n          method: 'tools/call',\n          serverName: this.name,\n          serverId: this.id,\n          serverUrl: this.traceUrl,\n          toolName: params.name,\n          input: JSON.stringify(params.arguments),\n          enabled: true,\n        },\n        async span => {\n          const result = await this.connection.callTool(params);\n          span.setOutput(JSON.stringify(result));\n          return result;\n        },\n      ),\n    );\n    if ('authRequired' in response) return response;\n    return { result: response.result, wasInitialized: response.wasInitialized };\n  }\n\n  toolCallInfo(params: CallToolRequest['params'], _resolveUnderlyingTool?: boolean): Promise<InternalToolCallInfo> {\n    void _resolveUnderlyingTool;\n    return Promise.resolve({\n      type: 'mcp',\n      original_tool_name: params.name,\n      mcp_server_id: this.id,\n      mcp_server_name: this.name,\n      is_approval_required: false,\n    });\n  }\n\n  private async connectIfNeeded(headers: Record<string, string>): Promise<MCPServerInitInfo | undefined> {\n    if (this.isConnected) return undefined;\n    if (this.connectPromise) {\n      // Wait for the in-flight connect, but only its originator emits the init metadata.\n      await this.connectPromise;\n      return undefined;\n    }\n\n    const existingSessionId = this.sessionId;\n    this.connectPromise = (async (): Promise<MCPServerInitInfo | undefined> => {\n      let connection: RemoteMcpConnection;\n      try {\n        await this.closeAndClearConnection();\n        connection = await this.tracing.withRemoteMcpToolSpan(\n          { method: 'initialize', serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },\n          async span => {\n            const conn = await connectRemoteMcp({\n              url: this.url,\n              headers,\n              sessionId: this.sessionId ?? undefined,\n              // Hint from a prior connect\n              knownTransportType: this.resolvedTransportType,\n              requestTimeoutMs: this.requestTimeoutMs,\n              connectTimeoutMs: this.connectTimeoutMs,\n              signal: this.signal,\n              onClose: () => {\n                this.isConnected = false;\n              },\n              onError: error => {\n                this.logger.error(`Error on remote MCP transport ${this.name}`, { error });\n              },\n            });\n            span.setOutput(JSON.stringify({ transport: conn.transportType, stateful: conn.sessionId !== null }));\n            return conn;\n          },\n        );\n      } catch (error) {\n        await this.closeAndClearConnection();\n        throw this.toConnectError(error);\n      }\n      this._connection = connection;\n      this.resolvedTransportType = connection.transportType;\n      this.isConnected = true;\n      this.sessionId = connection.sessionId;\n      if (existingSessionId === this.sessionId) {\n        return undefined;\n      }\n      return {\n        name: this.name,\n        id: this.id,\n        session_id: this.sessionId ?? undefined,\n        transport_type: this.resolvedTransportType,\n      };\n    })().finally(() => {\n      this.connectPromise = undefined;\n    });\n    return this.connectPromise;\n  }\n\n  private toConnectError(error: unknown): McpConnectionError {\n    const statusCode = error instanceof McpConnectionError ? error.statusCode : 502;\n    const message = error instanceof Error ? error.message : String(error);\n    return new McpConnectionError(`Failed to connect to remote MCP server '${this.name}': ${message}`, statusCode, {\n      cause: error,\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core/mcp/RemoteMCP.mjs

@@ -0,0 +1,222 @@
+// src/core/mcp/RemoteMCP.ts
+import { McpConnectionError } from "../errors.mjs";
+import { NOOP_AGENT_TRACING } from "../tracing/NoopAgentTracing.mjs";
+import "./IMCPServer.mjs";
+import { paginateWithCursorGuard } from "./pagination.mjs";
+import {
+  connectRemoteMcp,
+  isSessionExpiredError
+} from "./remoteMcpClient.mjs";
+function redactUrlForTrace(url) {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host}${u.pathname}`;
+  } catch {
+    return "";
+  }
+}
+var RemoteMCP = class {
+  name;
+  id;
+  description;
+  url;
+  headers;
+  signal;
+  logger;
+  tracing;
+  requestTimeoutMs;
+  connectTimeoutMs;
+  // Redacted display url for trace spans (derived from url; unused when tracing is a no-op).
+  traceUrl;
+  _connection;
+  isConnected = false;
+  connectPromise;
+  // undefined = never connected, string = stateful session id, null = stateless/SSE.
+  sessionId;
+  resolvedTransportType;
+  cachedTools;
+  constructor(params) {
+    this.name = params.name;
+    this.id = params.id;
+    this.description = params.description;
+    this.url = params.url;
+    this.headers = params.headers;
+    this.signal = params.signal;
+    this.sessionId = params.sessionId;
+    this.resolvedTransportType = params.transportType;
+    this.requestTimeoutMs = params.requestTimeoutMs;
+    this.connectTimeoutMs = params.connectTimeoutMs;
+    this.logger = params.logger;
+    this.tracing = params.tracing ?? NOOP_AGENT_TRACING;
+    this.traceUrl = redactUrlForTrace(params.url);
+  }
+  getSessionId() {
+    return this.sessionId ?? void 0;
+  }
+  get connection() {
+    if (!this._connection) {
+      throw new Error(`Remote MCP '${this.name}' not connected - connectIfNeeded() must run first`);
+    }
+    return this._connection;
+  }
+  async resetConnection() {
+    this.isConnected = false;
+    this.sessionId = void 0;
+    this.cachedTools = void 0;
+    this.connectPromise = void 0;
+    await this.closeAndClearConnection();
+  }
+  async closeAndClearConnection() {
+    await this._connection?.close().catch(() => {
+    });
+    this._connection = void 0;
+  }
+  async resolveHeaders() {
+    if (typeof this.headers !== "function") return { headers: this.headers };
+    return await this.headers();
+  }
+  async executeWithSessionRetry(operation) {
+    const headersResult = await this.resolveHeaders();
+    if ("authRequired" in headersResult) return { authRequired: headersResult.authRequired };
+    return this.connectAndRun(headersResult.headers, operation, true);
+  }
+  async connectAndRun(headers, operation, canRetry) {
+    try {
+      const initInfo = await this.connectIfNeeded(headers);
+      return { result: await operation(), wasInitialized: initInfo };
+    } catch (error) {
+      if (canRetry && isSessionExpiredError(error)) {
+        this.logger.info(`Session expired for remote MCP ${this.name}, reinitializing...`);
+        await this.resetConnection();
+        return this.connectAndRun(headers, operation, false);
+      }
+      throw error;
+    }
+  }
+  async loadTools() {
+    return this.tracing.withRemoteMcpToolSpan(
+      { method: "tools/list", serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },
+      async (span) => {
+        const tools = await paginateWithCursorGuard(
+          async (cursor) => {
+            const page = await this.connection.listTools(cursor);
+            return { items: page.tools, nextCursor: page.nextCursor };
+          },
+          this.name,
+          this.logger
+        );
+        this.cachedTools = tools.map((t) => ({ ...t, preload: true }));
+        span.setNumberOfTools(this.cachedTools.length);
+        return { tools: this.cachedTools };
+      }
+    );
+  }
+  /** Unfiltered tool list (no policy). The per-agent wrapper applies selectors on top. */
+  async listTools() {
+    if (this.cachedTools) {
+      return { result: { tools: this.cachedTools }, wasInitialized: void 0 };
+    }
+    const response = await this.executeWithSessionRetry(() => this.loadTools());
+    if ("authRequired" in response) return response;
+    return { result: { tools: response.result.tools }, wasInitialized: response.wasInitialized };
+  }
+  async callTool(params) {
+    const response = await this.executeWithSessionRetry(
+      () => this.tracing.withRemoteMcpToolSpan(
+        {
+          method: "tools/call",
+          serverName: this.name,
+          serverId: this.id,
+          serverUrl: this.traceUrl,
+          toolName: params.name,
+          input: JSON.stringify(params.arguments),
+          enabled: true
+        },
+        async (span) => {
+          const result = await this.connection.callTool(params);
+          span.setOutput(JSON.stringify(result));
+          return result;
+        }
+      )
+    );
+    if ("authRequired" in response) return response;
+    return { result: response.result, wasInitialized: response.wasInitialized };
+  }
+  toolCallInfo(params, _resolveUnderlyingTool) {
+    void _resolveUnderlyingTool;
+    return Promise.resolve({
+      type: "mcp",
+      original_tool_name: params.name,
+      mcp_server_id: this.id,
+      mcp_server_name: this.name,
+      is_approval_required: false
+    });
+  }
+  async connectIfNeeded(headers) {
+    if (this.isConnected) return void 0;
+    if (this.connectPromise) {
+      await this.connectPromise;
+      return void 0;
+    }
+    const existingSessionId = this.sessionId;
+    this.connectPromise = (async () => {
+      let connection;
+      try {
+        await this.closeAndClearConnection();
+        connection = await this.tracing.withRemoteMcpToolSpan(
+          { method: "initialize", serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },
+          async (span) => {
+            const conn = await connectRemoteMcp({
+              url: this.url,
+              headers,
+              sessionId: this.sessionId ?? void 0,
+              // Hint from a prior connect
+              knownTransportType: this.resolvedTransportType,
+              requestTimeoutMs: this.requestTimeoutMs,
+              connectTimeoutMs: this.connectTimeoutMs,
+              signal: this.signal,
+              onClose: () => {
+                this.isConnected = false;
+              },
+              onError: (error) => {
+                this.logger.error(`Error on remote MCP transport ${this.name}`, { error });
+              }
+            });
+            span.setOutput(JSON.stringify({ transport: conn.transportType, stateful: conn.sessionId !== null }));
+            return conn;
+          }
+        );
+      } catch (error) {
+        await this.closeAndClearConnection();
+        throw this.toConnectError(error);
+      }
+      this._connection = connection;
+      this.resolvedTransportType = connection.transportType;
+      this.isConnected = true;
+      this.sessionId = connection.sessionId;
+      if (existingSessionId === this.sessionId) {
+        return void 0;
+      }
+      return {
+        name: this.name,
+        id: this.id,
+        session_id: this.sessionId ?? void 0,
+        transport_type: this.resolvedTransportType
+      };
+    })().finally(() => {
+      this.connectPromise = void 0;
+    });
+    return this.connectPromise;
+  }
+  toConnectError(error) {
+    const statusCode = error instanceof McpConnectionError ? error.statusCode : 502;
+    const message = error instanceof Error ? error.message : String(error);
+    return new McpConnectionError(`Failed to connect to remote MCP server '${this.name}': ${message}`, statusCode, {
+      cause: error
+    });
+  }
+};
+export {
+  RemoteMCP
+};
+//# sourceMappingURL=RemoteMCP.mjs.map

package/dist/core/mcp/RemoteMCP.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/core/mcp/RemoteMCP.ts"],"sourcesContent":["import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';\nimport type { Logger } from 'winston';\nimport { McpConnectionError } from '../errors';\nimport type { MCPServerInitInfo } from '../events/schema';\nimport type { InternalToolCallInfo } from '../llm/LLMTypes';\nimport type { AgentTracing } from '../tracing/AgentTracing';\nimport { NOOP_AGENT_TRACING } from '../tracing/NoopAgentTracing';\nimport {\n  type AgentToolSchema,\n  type AuthRequiredResponse,\n  type CallToolResolvedResponse,\n  type ListToolsResolvedResponse,\n  type MCPAuthRequired,\n  type ToolSource,\n} from './IMCPServer';\nimport { paginateWithCursorGuard } from './pagination';\nimport {\n  connectRemoteMcp,\n  isSessionExpiredError,\n  type RemoteMcpConnection,\n  type RemoteMcpTransportType,\n} from './remoteMcpClient';\n\n/** Redacted url for trace spans: scheme + host + path only, so userinfo/query secrets never leak. */\nfunction redactUrlForTrace(url: string): string {\n  try {\n    const u = new URL(url);\n    return `${u.protocol}//${u.host}${u.pathname}`;\n  } catch {\n    return '';\n  }\n}\n\n/** What a headers resolver returns: the headers to send, or a signal that auth is required. */\nexport type ResolveHeadersResult = { headers: Record<string, string> } | { authRequired: MCPAuthRequired };\n\n/** Static headers, or a resolver (invoked at connect) returning headers or signalling auth-required. */\nexport type RemoteMcpHeaders = Record<string, string> | (() => Promise<ResolveHeadersResult>);\n\ntype ExecuteResult<T> = { result: T; wasInitialized: MCPServerInitInfo | undefined } | AuthRequiredResponse;\n\n/**\n * Connection/session half of a remote MCP server: owns the transport (connects itself from `url` +\n * `headers`), session id, raw tool cache, connect single-flight and session-expiry retry. Policy-free\n * — a per-agent {@link ToolSet} layers policy.\n */\nexport class RemoteMCP implements ToolSource {\n  readonly name: string;\n  readonly id: string;\n  readonly description?: string | undefined;\n\n  private readonly url: string;\n  private readonly headers: RemoteMcpHeaders;\n  private readonly signal: AbortSignal;\n  private readonly logger: Logger;\n  private readonly tracing: AgentTracing;\n  private readonly requestTimeoutMs: number;\n  private readonly connectTimeoutMs: number;\n  // Redacted display url for trace spans (derived from url; unused when tracing is a no-op).\n  private readonly traceUrl: string;\n\n  private _connection?: RemoteMcpConnection | undefined;\n  private isConnected = false;\n  private connectPromise: Promise<MCPServerInitInfo | undefined> | undefined;\n  // undefined = never connected, string = stateful session id, null = stateless/SSE.\n  private sessionId: string | null | undefined;\n  private resolvedTransportType?: RemoteMcpTransportType | undefined;\n  private cachedTools?: AgentToolSchema[] | undefined;\n\n  constructor(params: {\n    name: string;\n    id: string;\n    description?: string | undefined;\n    url: string;\n    headers: RemoteMcpHeaders;\n    logger: Logger;\n    tracing?: AgentTracing | undefined;\n    sessionId?: string | undefined;\n    transportType?: RemoteMcpTransportType | undefined;\n    requestTimeoutMs: number;\n    connectTimeoutMs: number;\n    signal: AbortSignal;\n  }) {\n    this.name = params.name;\n    this.id = params.id;\n    this.description = params.description;\n    this.url = params.url;\n    this.headers = params.headers;\n    this.signal = params.signal;\n    this.sessionId = params.sessionId;\n    this.resolvedTransportType = params.transportType;\n    this.requestTimeoutMs = params.requestTimeoutMs;\n    this.connectTimeoutMs = params.connectTimeoutMs;\n    this.logger = params.logger;\n    this.tracing = params.tracing ?? NOOP_AGENT_TRACING;\n    this.traceUrl = redactUrlForTrace(params.url);\n  }\n\n  getSessionId(): string | undefined {\n    return this.sessionId ?? undefined;\n  }\n\n  private get connection(): RemoteMcpConnection {\n    if (!this._connection) {\n      throw new Error(`Remote MCP '${this.name}' not connected - connectIfNeeded() must run first`);\n    }\n    return this._connection;\n  }\n\n  private async resetConnection(): Promise<void> {\n    this.isConnected = false;\n    this.sessionId = undefined;\n    this.cachedTools = undefined;\n    this.connectPromise = undefined;\n    await this.closeAndClearConnection();\n  }\n\n  private async closeAndClearConnection(): Promise<void> {\n    await this._connection?.close().catch(() => {\n      /* no-op */\n    });\n    this._connection = undefined;\n  }\n\n  private async resolveHeaders(): Promise<ResolveHeadersResult> {\n    if (typeof this.headers !== 'function') return { headers: this.headers };\n    return await this.headers();\n  }\n\n  private async executeWithSessionRetry<T>(operation: () => Promise<T>): Promise<ExecuteResult<T>> {\n    // Auth is re-checked on every operation, not only on the first connect: a registered server's OAuth\n    // can be revoked or expire mid-request, and callers must get authRequired rather than a generic\n    // upstream failure. When already connected the resolved headers are unused (connect is skipped).\n    const headersResult = await this.resolveHeaders();\n    if ('authRequired' in headersResult) return { authRequired: headersResult.authRequired };\n    return this.connectAndRun(headersResult.headers, operation, true);\n  }\n\n  private async connectAndRun<T>(\n    headers: Record<string, string>,\n    operation: () => Promise<T>,\n    canRetry: boolean,\n  ): Promise<ExecuteResult<T>> {\n    try {\n      const initInfo = await this.connectIfNeeded(headers);\n      return { result: await operation(), wasInitialized: initInfo };\n    } catch (error) {\n      if (canRetry && isSessionExpiredError(error)) {\n        this.logger.info(`Session expired for remote MCP ${this.name}, reinitializing...`);\n        await this.resetConnection();\n        return this.connectAndRun(headers, operation, false);\n      }\n      throw error;\n    }\n  }\n\n  private async loadTools(): Promise<{ tools: AgentToolSchema[] }> {\n    return this.tracing.withRemoteMcpToolSpan(\n      { method: 'tools/list', serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },\n      async span => {\n        const tools = await paginateWithCursorGuard(\n          async cursor => {\n            const page = await this.connection.listTools(cursor);\n            return { items: page.tools, nextCursor: page.nextCursor };\n          },\n          this.name,\n          this.logger,\n        );\n        this.cachedTools = tools.map(t => ({ ...t, preload: true }));\n        span.setNumberOfTools(this.cachedTools.length);\n        return { tools: this.cachedTools };\n      },\n    );\n  }\n\n  /** Unfiltered tool list (no policy). The per-agent wrapper applies selectors on top. */\n  async listTools(): Promise<ListToolsResolvedResponse | AuthRequiredResponse> {\n    if (this.cachedTools) {\n      return { result: { tools: this.cachedTools }, wasInitialized: undefined };\n    }\n    const response = await this.executeWithSessionRetry(() => this.loadTools());\n    if ('authRequired' in response) return response;\n    return { result: { tools: response.result.tools }, wasInitialized: response.wasInitialized };\n  }\n\n  async callTool(params: CallToolRequest['params']): Promise<CallToolResolvedResponse | AuthRequiredResponse> {\n    const response = await this.executeWithSessionRetry(() =>\n      this.tracing.withRemoteMcpToolSpan(\n        {\n          method: 'tools/call',\n          serverName: this.name,\n          serverId: this.id,\n          serverUrl: this.traceUrl,\n          toolName: params.name,\n          input: JSON.stringify(params.arguments),\n          enabled: true,\n        },\n        async span => {\n          const result = await this.connection.callTool(params);\n          span.setOutput(JSON.stringify(result));\n          return result;\n        },\n      ),\n    );\n    if ('authRequired' in response) return response;\n    return { result: response.result, wasInitialized: response.wasInitialized };\n  }\n\n  toolCallInfo(params: CallToolRequest['params'], _resolveUnderlyingTool?: boolean): Promise<InternalToolCallInfo> {\n    void _resolveUnderlyingTool;\n    return Promise.resolve({\n      type: 'mcp',\n      original_tool_name: params.name,\n      mcp_server_id: this.id,\n      mcp_server_name: this.name,\n      is_approval_required: false,\n    });\n  }\n\n  private async connectIfNeeded(headers: Record<string, string>): Promise<MCPServerInitInfo | undefined> {\n    if (this.isConnected) return undefined;\n    if (this.connectPromise) {\n      // Wait for the in-flight connect, but only its originator emits the init metadata.\n      await this.connectPromise;\n      return undefined;\n    }\n\n    const existingSessionId = this.sessionId;\n    this.connectPromise = (async (): Promise<MCPServerInitInfo | undefined> => {\n      let connection: RemoteMcpConnection;\n      try {\n        await this.closeAndClearConnection();\n        connection = await this.tracing.withRemoteMcpToolSpan(\n          { method: 'initialize', serverName: this.name, serverId: this.id, serverUrl: this.traceUrl, enabled: true },\n          async span => {\n            const conn = await connectRemoteMcp({\n              url: this.url,\n              headers,\n              sessionId: this.sessionId ?? undefined,\n              // Hint from a prior connect\n              knownTransportType: this.resolvedTransportType,\n              requestTimeoutMs: this.requestTimeoutMs,\n              connectTimeoutMs: this.connectTimeoutMs,\n              signal: this.signal,\n              onClose: () => {\n                this.isConnected = false;\n              },\n              onError: error => {\n                this.logger.error(`Error on remote MCP transport ${this.name}`, { error });\n              },\n            });\n            span.setOutput(JSON.stringify({ transport: conn.transportType, stateful: conn.sessionId !== null }));\n            return conn;\n          },\n        );\n      } catch (error) {\n        await this.closeAndClearConnection();\n        throw this.toConnectError(error);\n      }\n      this._connection = connection;\n      this.resolvedTransportType = connection.transportType;\n      this.isConnected = true;\n      this.sessionId = connection.sessionId;\n      if (existingSessionId === this.sessionId) {\n        return undefined;\n      }\n      return {\n        name: this.name,\n        id: this.id,\n        session_id: this.sessionId ?? undefined,\n        transport_type: this.resolvedTransportType,\n      };\n    })().finally(() => {\n      this.connectPromise = undefined;\n    });\n    return this.connectPromise;\n  }\n\n  private toConnectError(error: unknown): McpConnectionError {\n    const statusCode = error instanceof McpConnectionError ? error.statusCode : 502;\n    const message = error instanceof Error ? error.message : String(error);\n    return new McpConnectionError(`Failed to connect to remote MCP server '${this.name}': ${message}`, statusCode, {\n      cause: error,\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core/mcp/ToolSelectorPolicy.d.ts

@@ -0,0 +1,52 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { AgentToolSchema } from './IMCPServer';
+/**
+ * Per-server tool selectors. Enable/disable/preload tags: `@all`, `@read-only`.
+ * Approval tags: `@all`, `@write`, `@destructive`.
+ */
+export interface ToolSelectorConfig {
+    enableTools: string[];
+    disableTools: string[];
+    preloadTools: string[];
+    requireApprovalForTools?: string[] | undefined;
+}
+/**
+ * Encapsulates enable/disable/preload/approval selector policy for a single MCP server. Pure: it
+ * never throws or does IO — callers decide how to surface a disallowed/missing tool so each can
+ * raise its own error type.
+ */
+export declare class ToolSelectorPolicy {
+    readonly preload: boolean;
+    readonly hasPreloadedTools: boolean;
+    private readonly enableTools;
+    private readonly disableTools;
+    private readonly preloadTools;
+    private readonly requireApprovalForTools;
+    private resolvedAllowedToolNames;
+    constructor(params: {
+        selectors: ToolSelectorConfig;
+        preload: boolean;
+    });
+    /** Literal enable_tools names that are not present on the server (caller throws if non-empty). */
+    missingEnableLiterals(tools: AgentToolSchema[]): string[];
+    /** Filter by enable/disable, record the resolved allow-list, and annotate per-tool preload. */
+    filterAndAnnotate(tools: AgentToolSchema[]): AgentToolSchema[];
+    private isToolPreloaded;
+    /**
+     * Whether a tool may be called. Uses the resolved allow-list once listTools() has run; before that
+     * falls back to matching against the raw selectors, resolving annotations lazily only when needed.
+     */
+    isAllowed(toolName: string, resolveAnnotations: () => Promise<ToolAnnotations | undefined>): Promise<boolean>;
+    /**
+     * Best-effort allow-list for the sandbox. After a listTools() call returns the concrete names;
+     * before that, `@all` with no disables means "unrestricted" (undefined), else the literal names.
+     */
+    allowedNamesForSandbox(): string[] | undefined;
+    /**
+     * Whether the tool requires human approval. Honors `requireApprovalForTools` exactly: omit /
+     * undefined defaults to write+destructive (constructor); an explicit list — including empty —
+     * is exact.
+     */
+    requiresApproval(toolName: string, annotations: ToolAnnotations | undefined): boolean;
+}
+//# sourceMappingURL=ToolSelectorPolicy.d.ts.map

package/dist/core/mcp/ToolSelectorPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolSelectorPolicy.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/ToolSelectorPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uBAAuB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAChD;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAW;IAGnD,OAAO,CAAC,wBAAwB,CAAuB;IAEvD,YAAY,MAAM,EAAE;QAAE,SAAS,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAOtE;IAED,kGAAkG;IAClG,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAGxD;IAED,+FAA+F;IAC/F,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAW7D;IAED,OAAO,CAAC,eAAe;IAOvB;;;OAGG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAUlH;IAED;;;OAGG;IACH,sBAAsB,IAAI,MAAM,EAAE,GAAG,SAAS,CAQ7C;IAED;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAEpF;CACF"}