@apify/actors-mcp-server 0.11.7-beta.1 → 0.11.7-beta.10

package/dist/mcp/server.js

@@ -8,7 +8,7 @@ import { randomUUID } from 'node:crypto';
 import { getUiCapability, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, CallToolResultSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, RELATED_TASK_META_KEY, ServerNotificationSchema, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, CancelTaskRequestSchema, ErrorCode, GetPromptRequestSchema, GetTaskPayloadRequestSchema, GetTaskRequestSchema, InitializeRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListTasksRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, RELATED_TASK_META_KEY, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import dedent from 'dedent';
 import log from '@apify/log';
 import { parseBooleanOrNull } from '@apify/utilities';
@@ -19,29 +19,26 @@ import { prompts } from '../prompts/index.js';
 import { createResourceService } from '../resources/resource_service.js';
 import { resolveAvailableWidgets } from '../resources/widgets.js';
 import { getServerInfo } from '../server_card.js';
-import { buildReportedProblemProperties, getTelemetryEnv, trackReportedProblem, trackToolCall } from '../telemetry.js';
+import { getTelemetryEnv } from '../telemetry.js';
 import { decodeDotPropertyNames } from '../tools/actor_input_schema.js';
 import { legacyToolNameToNew } from '../tools/actor_tool_naming.js';
-import { actorExecutor } from '../tools/actors/actor_executor.js';
-import { buildPermissionApprovalResponse, checkPaymentProviderStandbyConflict } from '../tools/actors/call_actor.js';
-import { appendReportProblemNudge } from '../tools/dev/report_problem.js';
+import { checkPaymentProviderStandbyConflict } from '../tools/actors/call_actor.js';
+import { withReportProblemNudge } from '../tools/dev/report_problem.js';
 import { getActorsAsTools } from '../tools/index.js';
 import { SERVER_MODE, TOOL_TYPE } from '../types.js';
-import { isPermissionApprovalError, remoteMcpFailureDetail } from '../utils/apify_errors.js';
-import { getHttpStatusCode, isMcpClientFaultMessage, logHttpError, sanitizeMezmoMessage } from '../utils/logging.js';
-import { computeToolResponseBytes, getToolCallErrorUserText, respondErrorNoTelemetry, respondOk, } from '../utils/mcp.js';
+import { isMcpClientFaultMessage, logHttpError, sanitizeMezmoMessage } from '../utils/logging.js';
+import { respondOk } from '../utils/mcp.js';
 import { isReportProblemBlockedForClient } from '../utils/mcp_clients.js';
-import { buildPaymentRequiredResponse, isX402PaymentRequiredError } from '../utils/payment_errors.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
 import { parseServerMode, resolveServerMode } from '../utils/server_mode.js';
-import { applyToolTelemetry, classifyFailureCategory, deriveResourceIds, extractAjvErrorDetails, getToolStatusFromError, } from '../utils/tool_status.js';
+import { extractAjvErrorDetails } from '../utils/tool_status.js';
 import { buildActorFields, extractActorId, extractActorName, getToolFullName, getToolPublicFieldOnly, } from '../utils/tools.js';
 import { getActors, getToolsForServerMode, toolNamesToInput } from '../utils/tools_loader.js';
-import { getUserInfoCached } from '../utils/userid_cache.js';
-import { getPackageVersion } from '../utils/version.js';
-import { connectMCPClient } from './client.js';
-import { EXTERNAL_TOOL_CALL_TIMEOUT_MSEC, LOG_LEVEL_MAP } from './const.js';
+import { LOG_LEVEL_MAP } from './const.js';
+import { buildToolCallErrorResult, TOOL_CALL_ERROR_KIND } from './tool_call_error_mapper.js';
+import { logToolCallAndTelemetry, prepareTelemetryData } from './tool_call_telemetry.js';
+import { dispatchToolCall } from './tool_dispatch.js';
 import { createTaskCancellationWatcher, isTaskCancelled, isTaskNotFoundError, parseInputParamsFromUrl, storeTaskResultOrSkipIfExpired, } from './utils.js';
 /**
  * Returns true when the initialize request advertises the MCP Apps UI extension
@@ -199,18 +196,18 @@ export class ActorsMcpServer {
             writable: true,
             value: []
         });
-        // Telemetry configuration (resolved from options and env vars in setupTelemetry)
+        // Telemetry configuration (resolved from options and env vars, see setupTelemetry)
         Object.defineProperty(this, "telemetryEnabled", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: null
+            value: void 0
         });
         Object.defineProperty(this, "telemetryEnv", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: DEFAULT_TELEMETRY_ENV
+            value: void 0
         });
         // List of widgets that are ready to be served
         Object.defineProperty(this, "availableWidgets", {
@@ -277,7 +274,9 @@ export class ActorsMcpServer {
             },
             instructions: getServerInstructions(),
         });
-        this.setupTelemetry();
+        const { telemetryEnabled, telemetryEnv } = this.setupTelemetry();
+        this.telemetryEnabled = telemetryEnabled;
+        this.telemetryEnv = telemetryEnv;
         this.setupInitializeHandler();
         this.setupLoggingProxy();
         this.tools = new Map();
@@ -296,18 +295,21 @@ export class ActorsMcpServer {
      */
     setupTelemetry() {
         var _a, _b, _c;
+        let telemetryEnabled;
         const explicitEnabled = parseBooleanOrNull((_a = this.options.telemetry) === null || _a === void 0 ? void 0 : _a.enabled);
         if (explicitEnabled !== null) {
-            this.telemetryEnabled = explicitEnabled;
+            telemetryEnabled = explicitEnabled;
         }
         else {
             const envEnabled = parseBooleanOrNull(process.env.TELEMETRY_ENABLED);
-            this.telemetryEnabled = envEnabled !== null && envEnabled !== void 0 ? envEnabled : DEFAULT_TELEMETRY_ENABLED;
+            telemetryEnabled = envEnabled !== null && envEnabled !== void 0 ? envEnabled : DEFAULT_TELEMETRY_ENABLED;
         }
         // Configure telemetryEnv: explicit option > env var > default ('PROD')
-        if (this.telemetryEnabled) {
-            this.telemetryEnv = getTelemetryEnv((_c = (_b = this.options.telemetry) === null || _b === void 0 ? void 0 : _b.env) !== null && _c !== void 0 ? _c : process.env.TELEMETRY_ENV);
+        let telemetryEnv = DEFAULT_TELEMETRY_ENV;
+        if (telemetryEnabled) {
+            telemetryEnv = getTelemetryEnv((_c = (_b = this.options.telemetry) === null || _b === void 0 ? void 0 : _b.env) !== null && _c !== void 0 ? _c : process.env.TELEMETRY_ENV);
         }
+        return { telemetryEnabled, telemetryEnv };
     }
     /**
      * Override the SDK's `initialize` request handler to run mode resolution and
@@ -389,23 +391,10 @@ export class ActorsMcpServer {
      * survive a load that never sees an initialize.
      */
     isReportProblemServable() {
-        return (!!this.telemetryEnabled &&
+        return (this.telemetryEnabled &&
             this.clientKnown &&
             !isReportProblemBlockedForClient(this.options.initializeRequestData));
     }
-    /**
-     * Append the report-problem nudge to a failed tool result. Thin wrapper over
-     * {@link appendReportProblemNudge} that fills in whether report-problem is served on this
-     * connection; suppression by category/402 is handled inside the helper.
-     */
-    withReportProblemNudge(result, failingToolName, failureCategory, failureHttpStatus) {
-        return appendReportProblemNudge(result, {
-            failingToolName,
-            available: this.tools.has(HELPER_TOOLS.PROBLEM_REPORT),
-            failureCategory,
-            failureHttpStatus,
-        });
-    }
     composePendingToolsForClient() {
         if (this.pendingToolsUntilClientKnown.length === 0)
             return;
@@ -843,7 +832,7 @@ export class ActorsMcpServer {
          * @throws {McpError} - based on the McpServer class code from the typescript MCP SDK
          */
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _e;
             const params = request.params;
             // eslint-disable-next-line prefer-const
             let { name, arguments: args, _meta: meta } = params;
@@ -870,7 +859,13 @@ export class ActorsMcpServer {
                 // On a failed result, nudge the agent to report the blocker via report-problem at the
                 // moment it decides what to do next. Gated on the tool actually being served (see
                 // isReportProblemServable), so clients where it is blocklisted or telemetry is off never see it.
-                const augmented = this.withReportProblemNudge(r, resolvedToolName, callDiagnostics.failure_category, callDiagnostics.failure_http_status);
+                const augmented = withReportProblemNudge({
+                    result: r,
+                    tools: this.tools,
+                    failingToolName: resolvedToolName,
+                    failureCategory: callDiagnostics.failure_category,
+                    failureHttpStatus: callDiagnostics.failure_http_status,
+                });
                 toolResult = augmented;
                 return augmented;
             };
@@ -892,7 +887,12 @@ export class ActorsMcpServer {
             };
             // Initialize telemetry with raw tool name — updated below once the tool is resolved.
             // This ensures telemetry is available even for early failures (missing token, tool not found).
-            const { telemetryData, userId } = await this.prepareTelemetryData(name, mcpSessionId, apifyToken);
+            const { telemetryData, userId } = await prepareTelemetryData({
+                toolName: name,
+                mcpSessionId,
+                apifyToken,
+                apifyMcpServer: this,
+            });
             // actorName/actorId are declared here so they're available in the catch block for telemetry.
             // Set after tool resolution (inside the try block).
             let actorName;
@@ -1090,196 +1090,75 @@ export class ActorsMcpServer {
                     callDiagnostics = outcome.callDiagnostics;
                     return captureResult(outcome.result);
                 }
-                // Handle internal tool
-                if (tool.type === TOOL_TYPE.INTERNAL) {
-                    // Tools that may emit notifications/progress during a sync wait must be opted in here.
-                    // call-actor: emits during start+waitForFinish. get-actor-run: emits when waitSecs > 0.
-                    const progressTrackerOptIn = tool.name === HELPER_TOOLS.ACTOR_CALL || tool.name === HELPER_TOOLS.ACTOR_RUNS_GET;
-                    const progressTracker = progressTrackerOptIn
-                        ? createProgressTracker(progressToken, extra.sendNotification)
-                        : null;
-                    try {
-                        log.info('Calling internal tool', { toolName: tool.name, mcpSessionId, input: logSafeArgs });
-                        const res = (await tool.call({
-                            args: toolArgs,
-                            extra,
-                            apifyMcpServer: this,
-                            mcpServer: this.server,
-                            apifyToken,
-                            apifyClient: apifyClient,
-                            progressTracker,
-                            mcpSessionId,
-                        }));
-                        // Extract diagnostics and strip internal fields from res before returning to client.
-                        ({ toolStatus, callDiagnostics } = applyToolTelemetry(res, actorName, actorId, callDiagnostics));
-                        return captureResult(res);
-                    }
-                    finally {
-                        progressTracker === null || progressTracker === void 0 ? void 0 : progressTracker.stop();
-                    }
-                }
-                if (tool.type === TOOL_TYPE.ACTOR_MCP) {
-                    let client = null;
-                    try {
-                        client = await connectMCPClient(tool.serverUrl, apifyToken, mcpSessionId);
-                        if (!client) {
-                            const msg = dedent `
-                                Failed to connect to MCP server at "${tool.serverUrl}".
-                                Please verify the server URL is correct and accessible, and ensure you have a valid Apify token with appropriate permissions.
-                            `;
-                            log.softFail(msg, { mcpSessionId, failureCategory: FAILURE_CATEGORY.INTERNAL_ERROR });
-                            await this.server.sendLoggingMessage({ level: 'error', data: msg });
-                            toolStatus = TOOL_STATUS.SOFT_FAIL;
-                            callDiagnostics = { ...callDiagnostics, failure_category: FAILURE_CATEGORY.INTERNAL_ERROR };
-                            return captureResult(respondErrorNoTelemetry(msg));
-                        }
-                        // Only set up notification handlers if progressToken is provided by the client
-                        if (progressToken !== undefined && progressToken !== null) {
-                            // Set up notification handlers for the client
-                            for (const schema of ServerNotificationSchema.options) {
-                                const method = schema.shape.method.value;
-                                // Forward notifications from the proxy client to the server
-                                client.setNotificationHandler(schema, async (notification) => {
-                                    log.debug('Sending MCP notification', {
-                                        method,
-                                        mcpSessionId,
-                                        notification,
-                                    });
-                                    await extra.sendNotification(notification);
-                                });
-                            }
-                        }
-                        log.info('Calling Actor-MCP', {
-                            toolName: tool.name,
-                            actorMcpToolName: tool.originToolName,
-                            actorId: tool.actorId,
-                            mcpSessionId,
-                            input: logSafeArgs,
-                        });
-                        const res = await client.callTool({
-                            name: tool.originToolName,
-                            arguments: toolArgs,
-                            _meta: { progressToken },
-                        }, CallToolResultSchema, {
-                            timeout: EXTERNAL_TOOL_CALL_TIMEOUT_MSEC,
-                        });
-                        // TODO: actor-mcp responses are opaque — isError could be a user input problem
-                        // (e.g. invalid query) or a genuine server failure. We can't distinguish without
-                        // parsing the error text. Defaulting to INTERNAL_ERROR for now; revisit when
-                        // actor-mcp gets deeper telemetry treatment.
-                        if ('isError' in res && res.isError) {
-                            toolStatus = TOOL_STATUS.SOFT_FAIL;
-                            callDiagnostics = {
-                                failure_category: FAILURE_CATEGORY.INTERNAL_ERROR,
-                                ...buildActorFields(actorName, actorId),
-                            };
-                        }
-                        return captureResult({ ...res });
-                    }
-                    catch (error) {
-                        toolStatus = getToolStatusFromError(error, Boolean((_e = extra.signal) === null || _e === void 0 ? void 0 : _e.aborted));
-                        const failureDetail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
-                        callDiagnostics = {
-                            failure_category: classifyFailureCategory(error),
-                            failure_detail: failureDetail,
-                            ...buildActorFields(actorName, actorId),
-                        };
-                        logHttpError(error, `Failed to call MCP tool '${tool.originToolName}' on Actor '${tool.actorId}'`, {
-                            actorId: tool.actorId,
-                            toolName: tool.originToolName,
-                            failureCategory: callDiagnostics.failure_category,
-                        });
-                        return captureResult(respondErrorNoTelemetry(`Failed to call MCP tool '${tool.originToolName}' on Actor '${tool.actorId}': ${remoteMcpFailureDetail(error)}`));
-                    }
-                    finally {
-                        if (client)
-                            await client.close();
-                    }
-                }
-                // Handle actor tool
-                if (tool.type === TOOL_TYPE.ACTOR) {
-                    const progressTracker = createProgressTracker(progressToken, extra.sendNotification);
-                    try {
-                        log.info('Calling Actor', {
-                            toolName: tool.name,
-                            actorName: tool.actorFullName,
-                            mcpSessionId,
-                            input: logSafeArgs,
-                        });
-                        const executorResult = await actorExecutor.executeActorTool({
-                            actorFullName: tool.actorFullName,
-                            input: toolArgs,
-                            apifyClient: apifyClient,
-                            callOptions: { memory: tool.memoryMbytes },
-                            progressTracker,
-                            abortSignal: extra.signal,
-                            mcpSessionId,
-                            datasetItemsSchema: tool.datasetItemsSchema,
-                        });
-                        if (!executorResult) {
-                            toolStatus = TOOL_STATUS.ABORTED;
-                            // Receivers of cancellation notifications SHOULD NOT send a response for the cancelled request
-                            // https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation#behavior-requirements
-                            return captureResult({});
-                        }
-                        // Mirror the INTERNAL branch: read the telemetry the executor embedded on error
-                        // results (e.g. respondUserError → SOFT_FAIL/INVALID_INPUT), strip it from the wire,
-                        // and set failure_category so the report-problem nudge picks the softer variant.
-                        ({ toolStatus, callDiagnostics } = applyToolTelemetry(executorResult, actorName, actorId, callDiagnostics));
-                        return captureResult(executorResult);
-                    }
-                    finally {
-                        if (progressTracker) {
-                            progressTracker.stop();
-                        }
-                    }
-                }
-                // If we reached here without returning, it means the tool type was not recognized (user error)
-                toolStatus = TOOL_STATUS.SOFT_FAIL;
+                // Progress tracker: opt in for the two INTERNAL tools that emit during a sync wait
+                // (call-actor start+waitForFinish, get-actor-run when waitSecs > 0), and unconditionally
+                // for ACTOR tools. ACTOR_MCP forwards notifications directly, not via a tracker.
+                const progressTrackerOptIn = tool.type === TOOL_TYPE.ACTOR ||
+                    (tool.type === TOOL_TYPE.INTERNAL &&
+                        (tool.name === HELPER_TOOLS.ACTOR_CALL || tool.name === HELPER_TOOLS.ACTOR_RUNS_GET));
+                const progressTracker = progressTrackerOptIn
+                    ? createProgressTracker(progressToken, extra.sendNotification)
+                    : null;
+                const dispatchResult = await dispatchToolCall({
+                    tool,
+                    toolArgs: toolArgs,
+                    logSafeArgs,
+                    apifyToken,
+                    apifyClient: apifyClient,
+                    apifyMcpServer: this,
+                    mcpSessionId,
+                    progressToken,
+                    progressTracker,
+                    shouldForwardNotifications: true,
+                    extra,
+                    actorName,
+                    actorId,
+                    taskMode: false,
+                });
+                toolStatus = dispatchResult.toolStatus;
+                callDiagnostics = dispatchResult.callDiagnostics;
+                return captureResult(dispatchResult.result);
             }
             catch (error) {
-                const httpStatus = getHttpStatusCode(error);
+                // Re-throw MCP protocol errors (e.g. from failInvalidParams) so the SDK
+                // returns them as JSON-RPC errors. failInvalidParams already set callDiagnostics
+                // with the correct semantic category (e.g. AUTH), so we must not overwrite it.
+                // Re-throwing first is order-equivalent only because no McpError with an HTTP-range
+                // code reaches this catch: an McpError(402) WOULD satisfy the x402 predicate
+                // (getHttpStatusCode falls through to `.code`), but every remote-McpError route is
+                // sealed by an inner catch (ACTOR_MCP branch, call-actor MCP passthrough) and all
+                // in-repo McpErrors use negative ErrorCode.* values.
+                if (error instanceof McpError) {
+                    throw error;
+                }
+                const errorResult = buildToolCallErrorResult(error, {
+                    toolName: name,
+                    actorName,
+                    actorId,
+                    isAborted: Boolean((_e = extra.signal) === null || _e === void 0 ? void 0 : _e.aborted),
+                });
+                toolStatus = errorResult.toolStatus;
                 // Propagate 402 Payment Required as a tool result per x402 MCP transport spec:
-                // content[0].text (JSON) + isError: true. The concurrent-run limit falls through
-                // to the run-limit message below.
-                if (isX402PaymentRequiredError(error)) {
-                    toolStatus = TOOL_STATUS.SOFT_FAIL;
-                    callDiagnostics = {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        failure_http_status: 402,
-                        ...buildActorFields(actorName, actorId),
-                    };
-                    return captureResult(buildPaymentRequiredResponse(error));
+                // content[0].text (JSON) + isError: true. No log here (unlike the task path). The
+                // concurrent-run limit also surfaces as 402 but is excluded by the predicate and
+                // falls through to the generic run-limit handling below.
+                if (errorResult.kind === TOOL_CALL_ERROR_KIND.PAYMENT) {
+                    callDiagnostics = errorResult.callDiagnostics;
+                    return captureResult(errorResult.response);
                 }
-                if (isPermissionApprovalError(error)) {
-                    toolStatus = TOOL_STATUS.SOFT_FAIL;
-                    callDiagnostics = {
-                        failure_category: FAILURE_CATEGORY.PERMISSION_APPROVAL_REQUIRED,
-                        failure_http_status: error.statusCode,
-                        ...buildActorFields(actorName, actorId),
-                    };
+                if (errorResult.kind === TOOL_CALL_ERROR_KIND.APPROVAL) {
+                    callDiagnostics = errorResult.callDiagnostics;
                     logHttpError(error, 'Permission approval required while calling tool', {
                         toolName: name,
                         mcpSessionId,
                     });
-                    return captureResult(buildPermissionApprovalResponse(error));
+                    return captureResult(errorResult.response);
                 }
-                // Re-throw MCP protocol errors (e.g. from failInvalidParams) so the SDK
-                // returns them as JSON-RPC errors. failInvalidParams already set callDiagnostics
-                // with the correct semantic category (e.g. AUTH), so we must not overwrite it.
-                if (error instanceof McpError) {
-                    throw error;
-                }
-                toolStatus = getToolStatusFromError(error, Boolean((_f = extra.signal) === null || _f === void 0 ? void 0 : _f.aborted));
-                const failureDetail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
                 callDiagnostics = {
                     // Spread existing diagnostics first (e.g. validation_keyword from failInvalidParams),
-                    // then overwrite with freshly computed fields so they take precedence.
+                    // then overwrite with the mapper's freshly computed fields so they take precedence.
                     ...callDiagnostics,
-                    failure_category: classifyFailureCategory(error),
-                    ...(httpStatus !== undefined ? { failure_http_status: httpStatus } : {}),
-                    failure_detail: failureDetail,
-                    ...buildActorFields(actorName, actorId),
+                    ...errorResult.callDiagnostics,
                 };
                 logHttpError(error, 'Error occurred while calling tool', {
                     toolName: name,
@@ -1298,14 +1177,14 @@ export class ActorsMcpServer {
                 // reuse the local ABORTED-aware toolStatus, do NOT re-derive from the error (which
                 // would drop ABORTED and leak failureCategory/failureHttpStatus onto the wire).
                 return captureResult({
-                    ...respondOk(getToolCallErrorUserText(name, error)),
+                    ...respondOk(errorResult.userText),
                     isError: true,
                     toolTelemetry: { toolStatus },
                 });
             }
             finally {
                 if (shouldTrackTelemetry) {
-                    this.logToolCallAndTelemetry({
+                    logToolCallAndTelemetry({
                         toolName: resolvedToolName,
                         mcpSessionId,
                         toolStatus,
@@ -1316,73 +1195,13 @@ export class ActorsMcpServer {
                         args,
                         result: toolResult,
                         taskId: preflightTaskId,
+                        apifyMcpServer: this,
                     });
                 }
             }
-            const availableTools = this.listToolNames();
-            const msg = dedent `
-                Unknown tool type for "${name}".
-                Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
-                Please verify the tool name and ensure the tool is properly registered.
-            `;
-            log.softFail(msg, { mcpSessionId, statusCode: 404 });
-            await this.server.sendLoggingMessage({
-                level: 'error',
-                data: msg,
-            });
-            throw new McpError(ErrorCode.InvalidParams, msg);
-        });
-    }
-    /**
-     * Logs tool call completion at INFO level and tracks telemetry.
-     * Computes duration once so both the log line and telemetry event use the same value.
-     * Response bytes and resource ids are derived here from the raw `result` (+ `args`) so every
-     * call site stays a plain hand-off — no path can forget to compute or strip them.
-     */
-    logToolCallAndTelemetry(params) {
-        const durationMs = Date.now() - params.startTime;
-        // `result` is undefined only on short-circuit paths that never produced a payload (e.g. a
-        // cancelled task); skip byte accounting there. `null`/`{}` still measure as zero bytes.
-        const responseBytes = params.result === undefined ? undefined : computeToolResponseBytes(params.result);
-        log.info('Tool call completed', {
-            toolName: params.toolName,
-            mcpSessionId: params.mcpSessionId,
-            toolStatus: params.toolStatus,
-            durationMs,
-            ...(responseBytes !== undefined && {
-                responseContentBytes: responseBytes.contentBytes,
-                responseStructuredContentBytes: responseBytes.structuredContentBytes,
-                responseFileBytes: responseBytes.fileBytes,
-            }),
-            ...(params.taskId !== undefined && { taskId: params.taskId }),
         });
-        if (params.telemetryData) {
-            const finalizedTelemetryData = {
-                ...params.telemetryData,
-                tool_status: params.toolStatus,
-                tool_exec_time_ms: durationMs,
-                ...(responseBytes && {
-                    tool_response_content_bytes: responseBytes.contentBytes,
-                    tool_response_structured_content_bytes: responseBytes.structuredContentBytes,
-                    tool_response_file_bytes: responseBytes.fileBytes,
-                }),
-                // Always include actor_name/actor_id; failure-specific fields are only present when callDiagnostics has them.
-                ...params.callDiagnostics,
-                // Resource ids are read once here from the args + the tool's public output; no tool
-                // threads them back. Applied uniformly, last. See deriveResourceIds.
-                ...deriveResourceIds(params.args, params.result),
-            };
-            trackToolCall(params.userId, this.telemetryEnv, finalizedTelemetryData);
-            // A successful report-problem call also emits a dedicated feedback event carrying the
-            // submission. A downstream Segment destination fans it out to Slack/GitHub.
-            if (params.toolName === HELPER_TOOLS.PROBLEM_REPORT &&
-                params.toolStatus === TOOL_STATUS.SUCCEEDED &&
-                params.args) {
-                trackReportedProblem(params.userId, this.telemetryEnv, buildReportedProblemProperties(finalizedTelemetryData, params.args));
-            }
-        }
     }
-    // TODO: this function quite duplicates the main tool call login the CallToolRequestSchema handler, we should refactor
+    // TODO: outer orchestration here (pre-flight, telemetry bookkeeping, task-store handling) still duplicates the CallToolRequestSchema handler's logic; the dispatch ladder is now shared. Refactor.
     /**
      * Executes a tool asynchronously for a long-running task and updates task status.
      *
@@ -1408,9 +1227,14 @@ export class ActorsMcpServer {
         });
         // Prepare telemetry before try-catch so it's accessible to both paths.
         // This avoids re-fetching user data in the error handler.
-        const { telemetryData, userId } = await this.prepareTelemetryData(getToolFullName(tool), mcpSessionId, apifyToken);
+        const { telemetryData, userId } = await prepareTelemetryData({
+            toolName: getToolFullName(tool),
+            mcpSessionId,
+            apifyToken,
+            apifyMcpServer: this,
+        });
         const finishTaskTracking = (status, diagnostics, result) => {
-            this.logToolCallAndTelemetry({
+            logToolCallAndTelemetry({
                 toolName: tool.name,
                 mcpSessionId,
                 toolStatus: status,
@@ -1421,8 +1245,16 @@ export class ActorsMcpServer {
                 callDiagnostics: diagnostics,
                 args: toolArgs,
                 result,
+                apifyMcpServer: this,
             });
         };
+        // Terminal step shared by every task outcome: store the result (expiry-tolerant),
+        // emit the status notification, record telemetry.
+        const completeTask = async (storeStatus, taskResult, status, diagnostics) => {
+            await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, taskId, storeStatus, taskResult, mcpSessionId);
+            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
+            finishTaskTracking(status, diagnostics, taskResult);
+        };
         // Once a task is cancelled the spec forbids writing a result; every storage path
         // must short-circuit here. `logSuffix` is concatenated after "Task was cancelled"
         // so we keep the existing log format and the existing telemetry status per path.
@@ -1475,92 +1307,51 @@ export class ActorsMcpServer {
                 await this.taskStore.updateTaskStatus(taskId, 'working', message, mcpSessionId);
                 await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
             };
-            // Handle internal tool execution in task mode
-            if (toolStatus === TOOL_STATUS.SUCCEEDED && tool.type === TOOL_TYPE.INTERNAL) {
-                const progressTracker = createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
-                try {
-                    log.info('Calling internal tool for task', {
-                        taskId,
-                        toolName: tool.name,
-                        mcpSessionId,
-                        input: logSafeArgs,
-                    });
-                    const res = (await tool.call({
-                        args: toolArgs,
-                        extra: taskExtra,
-                        apifyMcpServer: this,
-                        mcpServer: this.server,
-                        apifyToken,
-                        apifyClient,
-                        progressTracker,
-                        mcpSessionId,
-                        taskMode: true,
-                    }));
-                    ({ toolStatus, callDiagnostics } = applyToolTelemetry(res, actorName, actorId, callDiagnostics));
-                    result = res;
-                }
-                finally {
-                    if (progressTracker) {
-                        progressTracker.stop();
-                    }
-                }
-            }
-            // Handle actor tool execution in task mode
-            if (toolStatus === TOOL_STATUS.SUCCEEDED && tool.type === TOOL_TYPE.ACTOR) {
-                const progressTracker = createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
-                try {
-                    log.info('Calling Actor for task', {
-                        taskId,
-                        toolName: tool.name,
-                        actorName: tool.actorFullName,
-                        mcpSessionId,
-                        input: logSafeArgs,
-                    });
-                    const executorResult = await actorExecutor.executeActorTool({
-                        actorFullName: tool.actorFullName,
-                        input: toolArgs,
-                        apifyClient,
-                        callOptions: { memory: tool.memoryMbytes },
-                        progressTracker,
-                        abortSignal: cancelWatcher.signal,
-                        mcpSessionId,
-                        datasetItemsSchema: tool.datasetItemsSchema,
-                        taskMode: true,
-                    });
-                    if (!executorResult) {
-                        toolStatus = TOOL_STATUS.ABORTED;
-                        // Receivers of cancellation notifications SHOULD NOT send a response for the cancelled request
-                        // https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation#behavior-requirements
-                        result = {};
-                    }
-                    else {
-                        // Mirror the INTERNAL task branch: extract embedded telemetry so failure_category
-                        // drives the success-path nudge below and toolTelemetry is stripped from the wire.
-                        ({ toolStatus, callDiagnostics } = applyToolTelemetry(executorResult, actorName, actorId, callDiagnostics));
-                        result = executorResult;
-                    }
-                }
-                finally {
-                    if (progressTracker) {
-                        progressTracker.stop();
-                    }
-                }
-            }
+            // ACTOR_MCP never reads the tracker (matching the sync path, which passes null for it);
+            // INTERNAL/ACTOR get one built from taskId + onStatusMessage, which dispatch consumes
+            // and stops.
+            const progressTracker = tool.type === TOOL_TYPE.ACTOR_MCP
+                ? null
+                : createProgressTracker(progressToken, extra.sendNotification, taskId, onStatusMessage);
+            const dispatchResult = await dispatchToolCall({
+                tool,
+                toolArgs,
+                logSafeArgs,
+                apifyToken,
+                apifyClient,
+                apifyMcpServer: this,
+                mcpSessionId,
+                progressToken,
+                progressTracker,
+                shouldForwardNotifications: false,
+                extra: taskExtra,
+                actorName,
+                actorId,
+                taskMode: true,
+                logContext: { messageSuffix: ' for task', fields: { taskId } },
+            });
+            result = dispatchResult.result;
+            toolStatus = dispatchResult.toolStatus;
+            callDiagnostics = dispatchResult.callDiagnostics;
             // Check if task was cancelled before storing result
             if (await skipIfTaskCancelled(', skipping result storage', toolStatus))
                 return;
             // On a failed result, nudge the agent to report the blocker via report-problem (mirrors the
             // synchronous CallTool path, which task-mode calls like call-actor bypass).
-            result = this.withReportProblemNudge(result, tool.name, callDiagnostics.failure_category, callDiagnostics.failure_http_status);
+            result = withReportProblemNudge({
+                result,
+                tools: this.tools,
+                failingToolName: tool.name,
+                failureCategory: callDiagnostics.failure_category,
+                failureHttpStatus: callDiagnostics.failure_http_status,
+            });
             // Store the result in the task store
             log.debug('[executeToolAndUpdateTask] Storing completed result', {
                 taskId,
                 mcpSessionId,
             });
-            await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, taskId, 'completed', result, mcpSessionId);
+            await completeTask('completed', result, toolStatus, callDiagnostics);
             log.debug('Task completed successfully', { taskId, toolName: tool.name, mcpSessionId });
-            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
-            finishTaskTracking(toolStatus, callDiagnostics, result);
         }
         catch (error) {
             // Reached only when the task expired before the `working` transition (updateTaskStatus
@@ -1579,9 +1370,14 @@ export class ActorsMcpServer {
                 });
                 return;
             }
+            const errorResult = buildToolCallErrorResult(error, {
+                toolName: tool.name,
+                actorName,
+                actorId,
+                isAborted: Boolean(cancelWatcher.signal.aborted),
+            });
             // Handle 402 Payment Required — return structured x402 result so clients can auto-pay
-            const httpStatus = getHttpStatusCode(error);
-            if (isX402PaymentRequiredError(error)) {
+            if (errorResult.kind === TOOL_CALL_ERROR_KIND.PAYMENT) {
                 logHttpError(error, 'Payment required while calling tool (task mode)', { toolName: tool.name });
                 // Per MCP tasks spec: once a task is cancelled it MUST remain cancelled,
                 // so guard storeTaskResult against a cancel that raced with this 402.
@@ -1589,17 +1385,10 @@ export class ActorsMcpServer {
                     ...buildActorFields(actorName, actorId),
                 }))
                     return;
-                const paymentResponse = buildPaymentRequiredResponse(error);
-                await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, taskId, 'completed', paymentResponse, mcpSessionId);
-                await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
-                finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
-                    failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                    failure_http_status: 402,
-                    ...buildActorFields(actorName, actorId),
-                }, paymentResponse);
+                await completeTask('completed', errorResult.response, errorResult.toolStatus, errorResult.callDiagnostics);
                 return;
             }
-            if (isPermissionApprovalError(error)) {
+            if (errorResult.kind === TOOL_CALL_ERROR_KIND.APPROVAL) {
                 logHttpError(error, 'Permission approval required while calling tool (task mode)', {
                     toolName: tool.name,
                 });
@@ -1609,24 +1398,11 @@ export class ActorsMcpServer {
                     ...buildActorFields(actorName, actorId),
                 }))
                     return;
-                const approvalResponse = buildPermissionApprovalResponse(error);
-                await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, taskId, 'completed', approvalResponse, mcpSessionId);
-                await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
-                finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
-                    failure_category: FAILURE_CATEGORY.PERMISSION_APPROVAL_REQUIRED,
-                    failure_http_status: error.statusCode,
-                    ...buildActorFields(actorName, actorId),
-                }, approvalResponse);
+                await completeTask('completed', errorResult.response, errorResult.toolStatus, errorResult.callDiagnostics);
                 return;
             }
-            toolStatus = getToolStatusFromError(error, Boolean(cancelWatcher.signal.aborted));
-            const failureDetail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
-            callDiagnostics = {
-                failure_category: classifyFailureCategory(error),
-                ...(httpStatus !== undefined ? { failure_http_status: httpStatus } : {}),
-                failure_detail: failureDetail,
-                ...buildActorFields(actorName, actorId),
-            };
+            toolStatus = errorResult.toolStatus;
+            callDiagnostics = errorResult.callDiagnostics;
             // Log level follows the already-classified toolStatus:
             //   SOFT_FAIL (e.g. 402/403 user quota, client-side issues) → softFail
             //   FAILED/ABORTED/other                                    → error
@@ -1656,7 +1432,7 @@ export class ActorsMcpServer {
                     error,
                 });
             }
-            const userText = getToolCallErrorUserText(tool.name, error);
+            const { userText } = errorResult;
             // Check if task was cancelled before storing result
             if (await skipIfTaskCancelled(', skipping result storage', toolStatus, callDiagnostics))
                 return;
@@ -1664,60 +1440,33 @@ export class ActorsMcpServer {
                 taskId,
                 mcpSessionId,
             });
-            // Nudge on a genuinely-failed task result. INTERNAL_ERROR and an unknown category get the
-            // full nudge; a genuine INVALID_INPUT gets the softer nudge; payment (402) is suppressed via
-            // the HTTP status and AUTH / PERMISSION_APPROVAL_REQUIRED via NON_NUDGE_FAILURE_CATEGORIES.
-            // The 402 branch above returns before reaching here, so this only sees non-payment failures.
-            const failedResult = this.withReportProblemNudge({
-                content: [
-                    {
-                        type: 'text',
-                        text: userText,
-                    },
-                ],
-                isError: true,
-                internalToolStatus: toolStatus,
-            }, tool.name, callDiagnostics.failure_category, callDiagnostics.failure_http_status);
-            await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, taskId, 'failed', failedResult, mcpSessionId);
-            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
-            finishTaskTracking(toolStatus, callDiagnostics, failedResult);
+            // Nudge on a genuinely-failed task result (mirrors the completed path and the sync
+            // captureResult). INTERNAL_ERROR and an unknown category get the full nudge; a genuine
+            // INVALID_INPUT gets the softer nudge; payment (402) is suppressed via the HTTP status and
+            // AUTH / PERMISSION_APPROVAL_REQUIRED via NON_NUDGE_FAILURE_CATEGORIES. The 402 branch above
+            // returns before reaching here, so this only sees non-payment failures.
+            const failedResult = withReportProblemNudge({
+                result: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: userText,
+                        },
+                    ],
+                    isError: true,
+                    internalToolStatus: toolStatus,
+                },
+                tools: this.tools,
+                failingToolName: tool.name,
+                failureCategory: callDiagnostics.failure_category,
+                failureHttpStatus: callDiagnostics.failure_http_status,
+            });
+            await completeTask('failed', failedResult, toolStatus, callDiagnostics);
         }
         finally {
             cancelWatcher.dispose();
         }
     }
-    /*
-     * Creates telemetry data for a tool call.
-     */
-    async prepareTelemetryData(toolName, mcpSessionId, apifyToken) {
-        var _a, _b, _c, _d, _e;
-        if (!this.telemetryEnabled) {
-            return { telemetryData: null, userId: null };
-        }
-        // Get userId from cache or fetch from API
-        let userId = null;
-        if (apifyToken) {
-            const apifyClient = new ApifyClient({ token: apifyToken });
-            ({ userId } = await getUserInfoCached(apifyToken, apifyClient));
-            log.debug('Telemetry: fetched userId', { userId, mcpSessionId });
-        }
-        const capabilities = (_b = (_a = this.options.initializeRequestData) === null || _a === void 0 ? void 0 : _a.params) === null || _b === void 0 ? void 0 : _b.capabilities;
-        const params = (_c = this.options.initializeRequestData) === null || _c === void 0 ? void 0 : _c.params;
-        const telemetryData = {
-            app: 'mcp',
-            app_version: getPackageVersion() || '',
-            mcp_client_name: ((_d = params === null || params === void 0 ? void 0 : params.clientInfo) === null || _d === void 0 ? void 0 : _d.name) || '',
-            mcp_client_version: ((_e = params === null || params === void 0 ? void 0 : params.clientInfo) === null || _e === void 0 ? void 0 : _e.version) || '',
-            mcp_protocol_version: (params === null || params === void 0 ? void 0 : params.protocolVersion) || '',
-            mcp_client_capabilities: capabilities || null,
-            mcp_session_id: mcpSessionId || '',
-            transport_type: this.options.transportType || '',
-            tool_name: toolName,
-            tool_status: TOOL_STATUS.SUCCEEDED, // Will be updated in finally
-            tool_exec_time_ms: 0, // Will be calculated in finally
-        };
-        return { telemetryData, userId };
-    }
     /**
      * Resolves widgets and determines which ones are ready to be served.
      */