@apify/actors-mcp-server 0.12.0 → 0.12.1-beta.1

package/dist/mcp/server.js

@@ -1,84 +1,40 @@
 /**
  * Model Context Protocol (MCP) server for Apify Actors
  */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b2bdac72-d12f-5751-9e08-72a36e12d99e")}catch(e){}}();
 import { randomUUID } from 'node:crypto';
-// The ext-apps package exposes `./server` via conditional exports only (no `./server/index.js`
-// wildcard), so we can't satisfy the `import/extensions` rule on this subpath.
-// eslint-disable-next-line import/extensions
-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, 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';
 import { ApifyClient } from '../apify_client.js';
-import { ALLOWED_TASK_TOOL_EXECUTION_MODES, DEFAULT_TELEMETRY_ENABLED, DEFAULT_TELEMETRY_ENV, FAILURE_CATEGORY, HELPER_TOOLS, TOOL_STATUS, } from '../const.js';
-import { prepareToolCallContext } from '../payments/helpers.js';
+import { DEFAULT_TELEMETRY_ENABLED, DEFAULT_TELEMETRY_ENV, FAILURE_CATEGORY, HELPER_TOOLS, TOOL_STATUS, } from '../const.js';
 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 { getTelemetryEnv } from '../telemetry.js';
-import { decodeDotPropertyNames } from '../tools/actor_input_schema.js';
-import { legacyToolNameToNew } from '../tools/actor_tool_naming.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 { isMcpClientFaultMessage, logHttpError, sanitizeMezmoMessage } from '../utils/logging.js';
-import { respondOk } from '../utils/mcp.js';
+import { isMcpClientFaultMessage, sanitizeMezmoMessage } from '../utils/logging.js';
 import { getRequestOriginForClient, isReportProblemBlockedForClient } from '../utils/mcp_clients.js';
-import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
 import { parseServerMode, resolveServerMode } from '../utils/server_mode.js';
-import { extractAjvErrorDetails } from '../utils/tool_status.js';
-import { buildActorFields, extractActorId, extractActorName, getToolFullName, getToolPublicFieldOnly, } from '../utils/tools.js';
+import { buildActorFields, getToolFullName, getToolPublicFieldOnly } from '../utils/tools.js';
 import { getActors, getToolsForServerMode, toolNamesToInput } from '../utils/tools_loader.js';
+import { buildMcpClientContext, isUiSupportedByClient } from './client_context.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 { buildPreflightFailureOutcome, classifyToolCallError, executeSyncToolCall, prepareToolCall, } from './tool_call_engine.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.
- *
- * Uses {@link getUiCapability} from `@modelcontextprotocol/ext-apps/server` to
- * read the `io.modelcontextprotocol/ui` extension from client capabilities — the
- * canonical way per the MCP Apps spec.
- */
-function isUiSupportedByClient(request) {
-    var _a, _b, _c;
-    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;
-}
-/**
- * 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
- * generic payment-required failure so the agent gets the precise reason instead of a generic 402.
- * Pure: callers own their own post-handling (return the result directly, or store + notify + synthesize
- * a terminal task) — call this only once `standbyRejection ?? paymentRequiredResult` is already truthy.
- */
-function buildPreflightFailureOutcome(standbyRejection, paymentRequiredResult, actorName, actorId) {
-    return {
-        toolStatus: TOOL_STATUS.SOFT_FAIL,
-        callDiagnostics: {
-            failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-            ...(standbyRejection ? {} : { failure_http_status: 402 }),
-            ...buildActorFields(actorName, actorId),
-        },
-        result: (standbyRejection !== null && standbyRejection !== void 0 ? standbyRejection : paymentRequiredResult),
-    };
-}
 /**
  * Create Apify MCP server
  */
 export class ActorsMcpServer {
     constructor(options = {}) {
+        var _a;
         Object.defineProperty(this, "server", {
             enumerable: true,
             configurable: true,
@@ -127,6 +83,12 @@ export class ActorsMcpServer {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "clientContext", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * Resolved server mode. Preliminary value at construction (`'auto'` → `DEFAULT`).
          * Finalized inside the `initialize` request handler (see constructor) once the
@@ -200,6 +162,7 @@ export class ActorsMcpServer {
             value: false
         });
         this.options = options;
+        this.clientContext = buildMcpClientContext((_a = options.initializeRequestData) === null || _a === void 0 ? void 0 : _a.params);
         // for stdio use in memory task store if not provided, otherwise use provided task store
         if (this.options.transportType === 'stdio' && !this.options.taskStore) {
             this.taskStore = new InMemoryTaskStore();
@@ -303,7 +266,9 @@ export class ActorsMcpServer {
         const sdkInitHandler = this.server._oninitialize.bind(this.server);
         this.server.setRequestHandler(InitializeRequestSchema, async (request) => {
             var _a;
-            this.clientSupportsUi = isUiSupportedByClient(request);
+            this.clientContext = buildMcpClientContext(request.params);
+            this.options.initializeRequestData = request;
+            this.clientSupportsUi = isUiSupportedByClient(this.clientContext);
             if (this.serverModeOption === 'auto') {
                 const resolved = resolveServerMode('auto', this.clientSupportsUi);
                 if (resolved !== this.serverMode) {
@@ -311,9 +276,6 @@ export class ActorsMcpServer {
                 }
                 this.serverModeResolved = true;
             }
-            // Setting this makes `clientKnown` true, so the queued compose below (and any later
-            // load) resolves the tool set for this client and applies the per-client blocklist.
-            this.options.initializeRequestData = request;
             log.info('Resolved server mode for client capabilities', {
                 serverMode: this.serverMode,
                 serverModeOption: this.serverModeOption,
@@ -334,7 +296,7 @@ export class ActorsMcpServer {
      *  recovery path). Only client-gated tools wait for this so the per-client blocklist can be
      *  applied; client-agnostic tools compose regardless. */
     get clientKnown() {
-        return this.options.initializeRequestData != null;
+        return this.clientContext != null;
     }
     /**
      * Compose the tool list for the current connection: resolve mode-specific tools, then drop
@@ -362,9 +324,7 @@ export class ActorsMcpServer {
      * survive a load that never sees an initialize.
      */
     isReportProblemServable() {
-        return (this.telemetryEnabled &&
-            this.clientKnown &&
-            !isReportProblemBlockedForClient(this.options.initializeRequestData));
+        return this.telemetryEnabled && this.clientKnown && !isReportProblemBlockedForClient(this.clientContext);
     }
     composePendingToolsForClient() {
         if (this.pendingToolsUntilClientKnown.length === 0)
@@ -468,7 +428,6 @@ export class ActorsMcpServer {
     /**
      * Loads missing toolNames from a provided list of tool names.
      * Skips toolNames that are already loaded and loads only the missing ones.
-     * @param toolNames - Array of tool names to ensure are loaded
      */
     async loadToolsByName(toolNames, apifyClient) {
         const loadedTools = new Set(this.listAllToolNames());
@@ -637,12 +596,12 @@ export class ActorsMcpServer {
      * Token-scoped client for resources/read (the API proxy needs auth). Deliberately token-only:
      * unlike the CallTool path it does NOT forward provider/payment headers, so a payment-only
      * session (x402/Skyfire, no Apify token) has no client and every read fails by design.
-     * Still carries the request-origin tag — `initializeRequestData` is already set by this point.
+     * Still carries the request-origin tag from the client context captured by this point.
      */
     resolveApifyClient(params) {
         const token = this.resolveApifyToken(params._meta);
         return token
-            ? new ApifyClient({ token, requestOrigin: getRequestOriginForClient(this.options.initializeRequestData) })
+            ? new ApifyClient({ token, requestOrigin: getRequestOriginForClient(this.clientContext) })
             : undefined;
     }
     setupResourceHandlers() {
@@ -661,41 +620,43 @@ export class ActorsMcpServer {
             return await resourceService.listResourceTemplates();
         });
     }
+    /**
+     * Returns the prompts/list result.
+     */
+    listPrompts() {
+        return { prompts };
+    }
+    /**
+     * Builds the prompts/get result: find → not-found → validate → render.
+     * Throws {@link McpError} for an unknown prompt name or invalid arguments (v1 behavior).
+     */
+    getPrompt(name, args) {
+        const prompt = prompts.find((p) => p.name === name);
+        if (!prompt) {
+            throw new McpError(ErrorCode.InvalidParams, `Prompt ${name} not found. Available prompts: ${prompts.map((p) => p.name).join(', ')}`);
+        }
+        if (!prompt.ajvValidate(args)) {
+            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${name}: args: ${JSON.stringify(args)} error: ${JSON.stringify(prompt.ajvValidate.errors)}`);
+        }
+        return {
+            description: prompt.description,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: prompt.render(args || {}),
+                    },
+                },
+            ],
+        };
+    }
     /**
      * Sets up MCP request handlers for prompts.
      */
     setupPromptHandlers() {
-        /**
-         * Handles the prompts/list request.
-         */
-        this.server.setRequestHandler(ListPromptsRequestSchema, () => {
-            return { prompts };
-        });
-        /**
-         * Handles the prompts/get request.
-         */
-        this.server.setRequestHandler(GetPromptRequestSchema, (request) => {
-            const { name, arguments: args } = request.params;
-            const prompt = prompts.find((p) => p.name === name);
-            if (!prompt) {
-                throw new McpError(ErrorCode.InvalidParams, `Prompt ${name} not found. Available prompts: ${prompts.map((p) => p.name).join(', ')}`);
-            }
-            if (!prompt.ajvValidate(args)) {
-                throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${name}: args: ${JSON.stringify(args)} error: ${JSON.stringify(prompt.ajvValidate.errors)}`);
-            }
-            return {
-                description: prompt.description,
-                messages: [
-                    {
-                        role: 'user',
-                        content: {
-                            type: 'text',
-                            text: prompt.render(args || {}),
-                        },
-                    },
-                ],
-            };
-        });
+        this.server.setRequestHandler(ListPromptsRequestSchema, () => this.listPrompts());
+        this.server.setRequestHandler(GetPromptRequestSchema, (request) => this.getPrompt(request.params.name, request.params.arguments));
     }
     /**
      * Fetches a task by ID, softFail-logging and throwing a client-facing McpError if it doesn't exist.
@@ -794,8 +755,9 @@ export class ActorsMcpServer {
          * `sendNotification`. Throws {@link McpError} to mirror the MCP SDK's McpServer error codes.
          */
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c;
             const params = request.params;
+            // Keep telemetry on the decoded arguments.
             // eslint-disable-next-line prefer-const
             let { name, arguments: args, _meta: meta } = params;
             const progressToken = meta === null || meta === void 0 ? void 0 : meta.progressToken;
@@ -816,157 +778,69 @@ export class ActorsMcpServer {
             // this handler's `finally` — so its `Tool call completed` log line keeps the taskId the
             // async path logs via finishTaskTracking.
             let preflightTaskId;
-            // Captured by `captureResult` so the `finally` block can measure response size for telemetry.
+            // The nudge must be included in the measured result.
             let toolResult = null;
-            const captureResult = (r) => {
-                // 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 = withReportProblemNudge({
-                    result: r,
-                    tools: this.tools,
-                    failingToolName: resolvedToolName,
-                    failureCategory: callDiagnostics.failure_category,
-                    failureHttpStatus: callDiagnostics.failure_http_status,
-                });
-                toolResult = augmented;
-                return augmented;
-            };
-            const failInvalidParams = async (message, details, logFields) => {
-                toolStatus = TOOL_STATUS.SOFT_FAIL;
-                callDiagnostics = details;
-                log.softFail(message, {
-                    mcpSessionId,
-                    failureCategory: details.failure_category,
-                    actorName: details.actor_name,
-                    validationKeyword: details.validation_keyword,
-                    validationPath: details.validation_path,
-                    validationMissingProperty: details.validation_missing_property,
-                    validationAdditionalProperty: details.validation_additional_property,
-                    ...logFields,
-                });
-                await this.server.sendLoggingMessage({ level: 'error', data: message });
-                throw new McpError(ErrorCode.InvalidParams, message);
-            };
-            // 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).
+            // Keep actor context available to the outer catch.
+            let actorName;
+            let actorId;
+            const { clientContext } = this;
+            // Start with the raw name so early failures still have telemetry.
             const { telemetryData, userId } = await prepareTelemetryData({
                 toolName: name,
                 mcpSessionId,
                 apifyToken,
                 apifyMcpServer: this,
+                clientContext,
             });
-            // 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;
-            let actorId;
             try {
-                // Validate token
-                if (!apifyToken &&
-                    !((_a = this.options.paymentProvider) === null || _a === void 0 ? void 0 : _a.allowsUnauthenticated) &&
-                    !this.options.allowUnauthMode) {
-                    await failInvalidParams(dedent `
-                    Apify API token is required but was not provided.
-                    Please set the APIFY_TOKEN environment variable or pass it as a parameter in the request header as Authorization Bearer <token>.
-                    You can get your Apify token from https://console.apify.com/account/integrations.
-                `, {
-                        failure_category: FAILURE_CATEGORY.AUTH,
-                    });
-                }
-                // TODO - if connection is /mcp client will not receive notification on tool change
-                // Find tool by name, actor full name, or legacy tool name (e.g. apify-slash-rag-web-browser → apify--rag-web-browser)
-                const newName = (_b = legacyToolNameToNew(name)) !== null && _b !== void 0 ? _b : name;
-                const toolEntry = Array.from(this.tools.values()).find((t) => t.name === newName || getToolFullName(t) === newName);
-                if (!toolEntry) {
-                    const availableTools = this.listToolNames();
-                    await failInvalidParams(dedent `
-                    Tool "${name}" was not found.
-                    Available tools: ${availableTools.length > 0 ? availableTools.join(', ') : 'none'}.
-                    Please verify the tool name is correct. You can list all available tools using the tools/list request.
-                `, {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                    });
-                }
-                const tool = toolEntry;
-                resolvedToolName = getToolFullName(tool);
-                // Update telemetry tool name now that we resolved the tool (uses actorFullName for actor tools).
-                if (telemetryData) {
-                    telemetryData.tool_name = resolvedToolName;
-                }
-                // Extract actor name/id for telemetry — available even when validation fails later.
-                actorName = extractActorName(tool, args);
-                actorId = extractActorId(tool);
-                // Always populate actor fields so they're tracked on both success and failure paths.
-                callDiagnostics = { ...callDiagnostics, ...buildActorFields(actorName, actorId) };
-                if (!args) {
-                    await failInvalidParams(dedent `
-                    Missing arguments for tool "${name}".
-                    Please provide the required arguments for this tool. Check the tool's input schema using ${HELPER_TOOLS.ACTOR_GET_DETAILS} tool to see what parameters are required.
-                `, {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        ...buildActorFields(actorName, actorId),
-                    });
-                }
-                // Decode dot property names in arguments before validation,
-                // since validation expects the original, non-encoded property names.
-                args = decodeDotPropertyNames(args);
-                // Centralize all payment processing: validate, strip payment fields, create client.
-                // Must run before AJV validation so toolArgsWithoutPayment doesn't contain provider-specific fields.
-                const { toolArgsWithoutPayment: toolArgs, toolArgsRedacted: logSafeArgs, apifyClient, paymentRequiredResult, } = prepareToolCallContext({
-                    provider: this.options.paymentProvider,
-                    tool,
-                    args: args,
+                const prepared = await prepareToolCall({
+                    apifyMcpServer: this,
                     apifyToken,
+                    name,
+                    args,
                     meta,
-                    requestHeaders: (_c = extra.requestInfo) === null || _c === void 0 ? void 0 : _c.headers,
-                    requestOrigin: getRequestOriginForClient(this.options.initializeRequestData),
+                    requestHeaders: (_a = extra.requestInfo) === null || _a === void 0 ? void 0 : _a.headers,
+                    isTaskRequest: Boolean(request.params.task),
+                    mcpSessionId,
+                    telemetryData,
+                    clientContext,
+                    extra,
                 });
-                log.debug('Validate arguments for tool', { toolName: tool.name, mcpSessionId, input: logSafeArgs });
-                if (!tool.ajvValidate(toolArgs)) {
-                    const errors = tool.ajvValidate.errors || [];
-                    const ajvErrorDetails = extractAjvErrorDetails(errors);
-                    const errorMessages = errors
-                        .map((e) => `${e.instancePath || 'root'}: ${e.message || 'validation error'}`)
-                        .join('; ');
-                    await failInvalidParams(dedent `
-                    Invalid arguments for tool "${tool.name}".
-                    Validation errors: ${errorMessages}.
-                    Please check the tool's input schema using ${HELPER_TOOLS.ACTOR_GET_DETAILS} tool and ensure all required parameters are provided with correct types and values.
-                `, {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        ...ajvErrorDetails,
-                        ...buildActorFields(actorName, actorId),
-                    });
+                if ('result' in prepared) {
+                    // The engine already classified this post-resolution failure.
+                    resolvedToolName = prepared.resolvedToolName;
+                    args = prepared.decodedArgs;
+                    toolStatus = prepared.toolStatus;
+                    callDiagnostics = prepared.callDiagnostics;
+                    toolResult = prepared.result;
+                    return prepared.result;
                 }
-                // Check if tool call is a long-running task and the tool supports that
-                // Cast to allowed task mode types ('optional' | 'required') for type-safe includes() check
-                const taskSupport = (_d = tool.execution) === null || _d === void 0 ? void 0 : _d.taskSupport;
-                if (request.params.task && !ALLOWED_TASK_TOOL_EXECUTION_MODES.includes(taskSupport)) {
-                    await failInvalidParams(dedent `
-                    Tool "${tool.name}" does not support long running task calls.
-                    Please remove the "task" parameter from the tool call request or use a different tool that supports long running tasks.
-                `, {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        ...buildActorFields(actorName, actorId),
+                if ('message' in prepared) {
+                    // Reproduce v1's invalid-params tail and preserve telemetry fields.
+                    resolvedToolName = (_b = prepared.resolvedToolName) !== null && _b !== void 0 ? _b : resolvedToolName;
+                    if (prepared.decodedArgs)
+                        args = prepared.decodedArgs;
+                    toolStatus = prepared.toolStatus;
+                    callDiagnostics = prepared.callDiagnostics;
+                    log.softFail(prepared.message, {
+                        mcpSessionId,
+                        failureCategory: prepared.callDiagnostics.failure_category,
+                        actorName: prepared.callDiagnostics.actor_name,
+                        validationKeyword: prepared.callDiagnostics.validation_keyword,
+                        validationPath: prepared.callDiagnostics.validation_path,
+                        validationMissingProperty: prepared.callDiagnostics.validation_missing_property,
+                        validationAdditionalProperty: prepared.callDiagnostics.validation_additional_property,
+                        ...prepared.logFields,
                     });
+                    await this.server.sendLoggingMessage({ level: 'error', data: prepared.message });
+                    throw new McpError(ErrorCode.InvalidParams, prepared.message);
                 }
-                // Standby / MCP-server Actors are never payable via a third-party provider —
-                // compute the rejection here so both the sync short-circuit and the task path
-                // can use it. In task-mode we still create the task and store this rejection
-                // as its result (instead of a generic 402), so the agent gets the precise reason
-                // when fetching the task result. Task-mode `call-actor` declares
-                // `taskSupport: 'optional'`, so without this both paths would 402 by default.
-                const { paymentProvider } = this.options;
-                const isCallActorTool = tool.name === HELPER_TOOLS.ACTOR_CALL || tool.name === HELPER_TOOLS.ACTOR_CALL_WIDGET;
-                const actorArg = toolArgs === null || toolArgs === void 0 ? void 0 : toolArgs.actor;
-                const standbyRejection = paymentProvider && isCallActorTool && typeof actorArg === 'string' && actorArg.length > 0
-                    ? await checkPaymentProviderStandbyConflict({
-                        actorName: actorArg,
-                        paymentProvider,
-                        apifyToken,
-                        mcpSessionId,
-                    })
-                    : null;
+                const { tool, toolArgs, logSafeArgs, apifyClient, standbyRejection, paymentRequiredResult } = prepared;
+                actorName = prepared.actorName;
+                actorId = prepared.actorId;
+                resolvedToolName = getToolFullName(tool);
+                // Telemetry uses the decoded arguments.
+                args = prepared.decodedArgs;
                 // TODO: we should split this huge method into smaller parts as it is slowly getting out of hand
                 // Handle long-running task request
                 if (request.params.task) {
@@ -1000,8 +874,7 @@ export class ActorsMcpServer {
                             // CreateTaskResult parse error; surface it as a protocol error instead.
                             // The pre-flight outcome left toolStatus=SOFT_FAIL, but a genuine store
                             // outage is a hard failure — correct it before throwing so the handler
-                            // `finally` logs FAILED/INTERNAL_ERROR (the outer McpError re-throw preserves
-                            // these), not the stale pre-flight SOFT_FAIL.
+                            // `finally` logs FAILED/INTERNAL_ERROR, not the stale pre-flight SOFT_FAIL.
                             toolStatus = TOOL_STATUS.FAILED;
                             callDiagnostics = {
                                 failure_category: FAILURE_CATEGORY.INTERNAL_ERROR,
@@ -1015,7 +888,14 @@ export class ActorsMcpServer {
                         setImmediate(() => {
                             void emitTaskStatusNotification(task.taskId, mcpSessionId, this.taskStore, this.server);
                         });
-                        captureResult(outcome.result);
+                        // Measure the nudged result without changing the stored result.
+                        toolResult = withReportProblemNudge({
+                            result: outcome.result,
+                            tools: this.tools,
+                            failingToolName: resolvedToolName,
+                            failureCategory: callDiagnostics.failure_category,
+                            failureHttpStatus: callDiagnostics.failure_http_status,
+                        });
                         // createTask returned status `working`; synthesize the terminal status instead of
                         // re-fetching — if the task expired before the result store (the one case
                         // storeTaskResultOrSkipIfExpired tolerates), a re-fetch would come back empty and a
@@ -1027,9 +907,9 @@ export class ActorsMcpServer {
                         executeToolAndUpdateTask({
                             taskId: task.taskId,
                             tool,
-                            toolArgs: toolArgs,
+                            toolArgs,
                             logSafeArgs,
-                            apifyClient: apifyClient,
+                            apifyClient,
                             apifyToken,
                             progressToken,
                             extra,
@@ -1037,6 +917,7 @@ export class ActorsMcpServer {
                             actorName,
                             actorId,
                             apifyMcpServer: this,
+                            clientContext,
                         }).catch((error) => 
                         // Benign task-expiry is handled in-method (see the catch block and
                         // storeTaskResultOrSkipIfExpired); anything reaching here is genuinely unexpected.
@@ -1046,116 +927,38 @@ export class ActorsMcpServer {
                     shouldTrackTelemetry = false;
                     return { task };
                 }
-                // Sync path: short-circuit on either pre-flight failure. buildPreflightFailureOutcome
-                // encodes the precedence — standby rejection wins over the generic payment-required
-                // 402, so the agent gets the precise reason.
-                if (standbyRejection || paymentRequiredResult) {
-                    const outcome = buildPreflightFailureOutcome(standbyRejection, paymentRequiredResult, actorName, actorId);
-                    toolStatus = outcome.toolStatus;
-                    callDiagnostics = outcome.callDiagnostics;
-                    return captureResult(outcome.result);
-                }
-                // 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,
+                // Sync path: run the shared dispatch tail and project its neutral outcome by identity.
+                const outcome = await executeSyncToolCall(prepared, {
                     apifyMcpServer: this,
+                    apifyToken,
+                    toolName: name,
                     mcpSessionId,
                     progressToken,
-                    progressTracker,
-                    shouldForwardNotifications: true,
                     extra,
-                    actorName,
-                    actorId,
-                    taskMode: false,
                 });
-                toolStatus = dispatchResult.toolStatus;
-                callDiagnostics = dispatchResult.callDiagnostics;
-                return captureResult(dispatchResult.result);
+                toolStatus = outcome.toolStatus;
+                callDiagnostics = outcome.callDiagnostics;
+                toolResult = outcome.result;
+                return outcome.result;
             }
             catch (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.
+                // Match v1: classify task-creation failures, but re-throw protocol errors as JSON-RPC.
                 if (error instanceof McpError) {
                     throw error;
                 }
-                const errorResult = buildToolCallErrorResult(error, {
+                const outcome = classifyToolCallError(error, {
+                    apifyMcpServer: this,
                     toolName: name,
+                    failingToolName: resolvedToolName,
                     actorName,
                     actorId,
-                    isAborted: Boolean((_e = extra.signal) === null || _e === void 0 ? void 0 : _e.aborted),
+                    isAborted: Boolean((_c = extra.signal) === null || _c === void 0 ? void 0 : _c.aborted),
+                    mcpSessionId,
                 });
-                toolStatus = errorResult.toolStatus;
-                switch (errorResult.kind) {
-                    case TOOL_CALL_ERROR_KIND.PAYMENT: {
-                        // Propagate 402 Payment Required as a tool result per x402 MCP transport spec:
-                        // 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.
-                        callDiagnostics = errorResult.callDiagnostics;
-                        return captureResult(errorResult.response);
-                    }
-                    case TOOL_CALL_ERROR_KIND.APPROVAL: {
-                        callDiagnostics = errorResult.callDiagnostics;
-                        logHttpError(error, 'Permission approval required while calling tool', {
-                            toolName: name,
-                            mcpSessionId,
-                        });
-                        return captureResult(errorResult.response);
-                    }
-                    case TOOL_CALL_ERROR_KIND.EXECUTION: {
-                        callDiagnostics = {
-                            // Spread existing diagnostics first (e.g. validation_keyword from
-                            // failInvalidParams), then overwrite with the mapper's freshly computed fields
-                            // so they take precedence.
-                            ...callDiagnostics,
-                            ...errorResult.callDiagnostics,
-                        };
-                        logHttpError(error, 'Error occurred while calling tool', {
-                            toolName: name,
-                            toolStatus,
-                            mcpSessionId,
-                            failureCategory: callDiagnostics.failure_category,
-                            failureHttpStatus: callDiagnostics.failure_http_status,
-                            actorName: callDiagnostics.actor_name,
-                            validationKeyword: callDiagnostics.validation_keyword,
-                            validationPath: callDiagnostics.validation_path,
-                            validationMissingProperty: callDiagnostics.validation_missing_property,
-                            validationAdditionalProperty: callDiagnostics.validation_additional_property,
-                        });
-                        // This framework outer-catch path bypasses extractToolTelemetry (returned via
-                        // captureResult), so preserve the pre-existing wire shape { toolStatus } exactly:
-                        // 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(errorResult.userText),
-                            isError: true,
-                            toolTelemetry: { toolStatus },
-                        });
-                    }
-                    default:
-                        // Compile-time exhaustiveness guard (same `satisfies never` idiom as
-                        // dispatchToolCall's default arm): a new TOOL_CALL_ERROR_KIND makes `errorResult`
-                        // non-`never` here and fails to compile. Unreachable at runtime.
-                        throw new McpError(ErrorCode.InvalidParams, `Unknown tool-call error kind "${errorResult.kind}"`);
-                }
+                toolStatus = outcome.toolStatus;
+                callDiagnostics = outcome.callDiagnostics;
+                toolResult = outcome.result;
+                return outcome.result;
             }
             finally {
                 if (shouldTrackTelemetry) {
@@ -1240,5 +1043,4 @@ export class ActorsMcpServer {
         await this.server.close();
     }
 }
-//# sourceMappingURL=server.js.map
-//# debugId=b2bdac72-d12f-5751-9e08-72a36e12d99e
+//# sourceMappingURL=server.js.map