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

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,30 +19,28 @@ 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 { createTaskCancellationWatcher, isTaskCancelled, isTaskNotFoundError, parseInputParamsFromUrl, storeTaskResultOrSkipIfExpired, } from './utils.js';
+import { LOG_LEVEL_MAP } from './const.js';
+import { emitTaskStatusNotification, executeToolAndUpdateTask } from './task_execution.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 { parseInputParamsFromUrl, storeTaskResultOrSkipIfExpired } from './utils.js';
 /**
  * Returns true when the initialize request advertises the MCP Apps UI extension
  * with the widget MIME type. Used to resolve `'auto'` server mode.
@@ -56,33 +54,6 @@ function isUiSupportedByClient(request) {
     const uiCap = getUiCapability((_a = request === null || request === void 0 ? void 0 : request.params) === null || _a === void 0 ? void 0 : _a.capabilities);
     return (_c = (_b = uiCap === null || uiCap === void 0 ? void 0 : uiCap.mimeTypes) === null || _b === void 0 ? void 0 : _b.includes(RESOURCE_MIME_TYPE)) !== null && _c !== void 0 ? _c : false;
 }
-/** Send notifications/tasks/status for taskId. Routes via session transport (no relatedRequestId).
- *  Swallows errors — notifications are advisory. */
-export async function emitTaskStatusNotification(taskId, mcpSessionId, taskStore, server) {
-    try {
-        const task = await taskStore.getTask(taskId, mcpSessionId);
-        if (!task)
-            return;
-        // Per spec: notifications/tasks/status MUST NOT carry _meta.related-task (task ID is in params).
-        // Called without options so the notification routes through the session transport,
-        // not the request-scoped stream (which closes once the initial { task } response is flushed).
-        await server.notification({
-            method: 'notifications/tasks/status',
-            params: {
-                taskId: task.taskId,
-                status: task.status,
-                createdAt: task.createdAt,
-                lastUpdatedAt: task.lastUpdatedAt,
-                ttl: task.ttl,
-                ...(task.statusMessage != null && { statusMessage: task.statusMessage }),
-                ...(task.pollInterval != null && { pollInterval: task.pollInterval }),
-            },
-        });
-    }
-    catch {
-        // Silent fail — notifications are advisory
-    }
-}
 /**
  * Shared diagnostics for a pre-flight failure (standby-provider conflict or missing/invalid payment
  * signature) — a call outcome already known before any Actor runs. Standby rejection wins over the
@@ -199,18 +170,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 +248,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 +269,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 +365,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 +806,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 +833,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 +861,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;
@@ -1060,7 +1034,7 @@ export class ActorsMcpServer {
                     }
                     // Execute the tool asynchronously and update task status
                     setImmediate(() => {
-                        this.executeToolAndUpdateTask({
+                        executeToolAndUpdateTask({
                             taskId: task.taskId,
                             tool,
                             toolArgs: toolArgs,
@@ -1072,6 +1046,7 @@ export class ActorsMcpServer {
                             mcpSessionId,
                             actorName,
                             actorId,
+                            apifyMcpServer: this,
                         }).catch((error) => 
                         // Benign task-expiry is handled in-method (see the catch block and
                         // storeTaskResultOrSkipIfExpired); anything reaching here is genuinely unexpected.
@@ -1090,196 +1065,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));
-                }
-                // 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;
+                    return captureResult(errorResult.response);
                 }
-                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 +1152,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,407 +1170,11 @@ export class ActorsMcpServer {
                         args,
                         result: toolResult,
                         taskId: preflightTaskId,
-                    });
-                }
-            }
-            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
-    /**
-     * Executes a tool asynchronously for a long-running task and updates task status.
-     *
-     * @param params - Tool execution parameters
-     * @param params.taskId - The task identifier
-     * @param params.tool - The tool to execute
-     * @param params.args - Tool arguments
-     * @param params.apifyToken - Apify API token
-     * @param params.progressToken - Progress token for notifications
-     * @param params.extra - Extra request handler context
-     * @param params.mcpSessionId - MCP session ID for telemetry
-     */
-    async executeToolAndUpdateTask(params) {
-        const { taskId, tool, toolArgs, logSafeArgs, apifyClient, apifyToken, progressToken, extra, mcpSessionId, actorName, actorId, } = params;
-        let toolStatus = TOOL_STATUS.SUCCEEDED;
-        // Always populate actor fields so they're tracked on both success and failure paths.
-        let callDiagnostics = { ...buildActorFields(actorName, actorId) };
-        const startTime = Date.now();
-        log.debug('[executeToolAndUpdateTask] Starting task execution', {
-            taskId,
-            toolName: tool.name,
-            mcpSessionId,
-        });
-        // 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 finishTaskTracking = (status, diagnostics, result) => {
-            this.logToolCallAndTelemetry({
-                toolName: tool.name,
-                mcpSessionId,
-                toolStatus: status,
-                startTime,
-                taskId,
-                telemetryData,
-                userId,
-                callDiagnostics: diagnostics,
-                args: toolArgs,
-                result,
-            });
-        };
-        // 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.
-        const skipIfTaskCancelled = async (logSuffix, status, diagnostics) => {
-            if (!(await isTaskCancelled(taskId, mcpSessionId, this.taskStore)))
-                return false;
-            log.debug(`[executeToolAndUpdateTask] Task was cancelled${logSuffix}`, { taskId, mcpSessionId });
-            finishTaskTracking(status, diagnostics);
-            return true;
-        };
-        // Bridges MCP `tasks/cancel` to the running handler: when the client
-        // explicitly cancels the task, this signal aborts so the underlying
-        // Actor run stops instead of consuming compute until natural completion.
-        // Per MCP tasks spec, request-level aborts (client disconnect,
-        // notifications/cancelled for the original request ID) MUST NOT cancel
-        // the task — `extra.signal` is intentionally not chained here.
-        const cancelWatcher = createTaskCancellationWatcher({
-            taskId,
-            mcpSessionId,
-            taskStore: this.taskStore,
-        });
-        const taskExtra = { ...extra, signal: cancelWatcher.signal };
-        try {
-            log.debug('[executeToolAndUpdateTask] Updating task status to working', {
-                taskId,
-                mcpSessionId,
-            });
-            // The store rejects terminal → 'working' transitions. If `tasks/cancel` raced
-            // with us (between handler dispatch and the first watcher tick at ~500 ms),
-            // updateTaskStatus throws — re-check the store to tell a clean cancel-race
-            // apart from a genuine store error.
-            // noinspection ExceptionCaughtLocallyJS
-            try {
-                await this.taskStore.updateTaskStatus(taskId, 'working', undefined, mcpSessionId);
-            }
-            catch (err) {
-                if (await skipIfTaskCancelled(' before execution started, skipping', TOOL_STATUS.ABORTED, {
-                    ...buildActorFields(actorName, actorId),
-                }))
-                    return;
-                throw err;
-            }
-            await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
-            // Execute the tool and get the result
-            let result = {};
-            // Callback to propagate Actor run statusMessage into the task store and emit a push notification.
-            // TODO(TC-3): cancel arriving while this is scheduled throws cancelled → working;
-            // currently swallowed by progress.ts's tick catch — guard or catch explicitly.
-            const onStatusMessage = async (message) => {
-                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();
-                    }
                 }
             }
-            // 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);
-            // 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);
-            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
-            // above rethrows the store's unknown-taskId error). The tool never ran and the task is
-            // gone, so soft-fail, record telemetry, and stop. Every result store (success and error
-            // paths) tolerates expiry via storeTaskResultOrSkipIfExpired, so they don't reach here.
-            if (isTaskNotFoundError(error)) {
-                log.softFail('Task expired before execution started', {
-                    taskId,
-                    toolName: tool.name,
-                    mcpSessionId,
-                });
-                finishTaskTracking(TOOL_STATUS.SOFT_FAIL, {
-                    failure_category: FAILURE_CATEGORY.INTERNAL_ERROR,
-                    ...buildActorFields(actorName, actorId),
-                });
-                return;
-            }
-            // Handle 402 Payment Required — return structured x402 result so clients can auto-pay
-            const httpStatus = getHttpStatusCode(error);
-            if (isX402PaymentRequiredError(error)) {
-                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.
-                if (await skipIfTaskCancelled(', skipping 402 result storage', TOOL_STATUS.ABORTED, {
-                    ...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);
-                return;
-            }
-            if (isPermissionApprovalError(error)) {
-                logHttpError(error, 'Permission approval 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 approval error.
-                if (await skipIfTaskCancelled(', skipping permission-approval result storage', TOOL_STATUS.ABORTED, {
-                    ...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);
-                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),
-            };
-            // Log level follows the already-classified toolStatus:
-            //   SOFT_FAIL (e.g. 402/403 user quota, client-side issues) → softFail
-            //   FAILED/ABORTED/other                                    → error
-            if (toolStatus === TOOL_STATUS.SOFT_FAIL) {
-                // Mezmo promotes on "error" in message/keys — use errMessage key, sanitized.
-                const errMessage = sanitizeMezmoMessage(error instanceof Error ? error.message : String(error));
-                log.softFail('Tool execution soft-failed for task', {
-                    taskId,
-                    toolName: tool.name,
-                    toolStatus,
-                    mcpSessionId,
-                    failureCategory: callDiagnostics.failure_category,
-                    failureHttpStatus: callDiagnostics.failure_http_status,
-                    actorName: callDiagnostics.actor_name,
-                    errMessage,
-                });
-            }
-            else {
-                log.error('Error executing tool for task', {
-                    taskId,
-                    toolName: tool.name,
-                    toolStatus,
-                    mcpSessionId,
-                    failureCategory: callDiagnostics.failure_category,
-                    failureHttpStatus: callDiagnostics.failure_http_status,
-                    actorName: callDiagnostics.actor_name,
-                    error,
-                });
-            }
-            const userText = getToolCallErrorUserText(tool.name, error);
-            // Check if task was cancelled before storing result
-            if (await skipIfTaskCancelled(', skipping result storage', toolStatus, callDiagnostics))
-                return;
-            log.debug('[executeToolAndUpdateTask] Storing failed result', {
-                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);
-        }
-        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.