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

package/dist/mcp/server.js

@@ -19,21 +19,23 @@ 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, trackToolCall } from '../telemetry.js';
+import { buildReportedProblemProperties, getTelemetryEnv, trackReportedProblem, trackToolCall } 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 { 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 { 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 { classifyFailureCategory, deriveResourceIds, extractAjvErrorDetails, extractToolTelemetry, getToolStatusFromError, } from '../utils/tool_status.js';
+import { applyToolTelemetry, classifyFailureCategory, deriveResourceIds, extractAjvErrorDetails, getToolStatusFromError, } 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';
@@ -81,6 +83,24 @@ export async function emitTaskStatusNotification(taskId, mcpSessionId, taskStore
         // 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
+ * 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
  */
@@ -156,7 +176,10 @@ export class ActorsMcpServer {
             writable: true,
             value: void 0
         });
-        /** True once mode is final. False for `'auto'` until the initialize handler resolves client capabilities. */
+        /** True once the server mode is final: at construction for explicit `default`/`apps`, or after
+         *  the initialize handler resolves `'auto'`. Composing before this in `'auto'` mode would use
+         *  the preliminary DEFAULT mode and produce the wrong (non-widget) tool variants, so composition
+         *  waits for it. Distinct from {@link clientKnown}, which only withholds client-gated tools. */
         Object.defineProperty(this, "serverModeResolved", {
             enumerable: true,
             configurable: true,
@@ -164,12 +187,13 @@ export class ActorsMcpServer {
             value: void 0
         });
         /**
-         * Tool requests queued before mode is final. Actor tools are upserted immediately
-         * (mode-agnostic); we also capture the exact actor-tool slice fetched for each
-         * request so the flush composes every entry against *its own* actor list rather
-         * than the accumulated union across unrelated requests.
+         * Tool sources queued until composition is possible. Enqueued when the mode is not yet resolved
+         * (`'auto'` before initialize), and re-composed by the initialize flush — which is also when the
+         * client becomes known, so any client-gated tools withheld by an eager compose are added then.
+         * We capture the exact actor-tool slice fetched for each request so the flush composes every
+         * entry against *its own* actor list rather than the accumulated union across unrelated requests.
          */
-        Object.defineProperty(this, "pendingToolsAfterModeResolved", {
+        Object.defineProperty(this, "pendingToolsUntilClientKnown", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -314,6 +338,8 @@ 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,
@@ -321,23 +347,74 @@ export class ActorsMcpServer {
                 clientSupportsUi: this.clientSupportsUi,
                 capabilities: (_a = request === null || request === void 0 ? void 0 : request.params) === null || _a === void 0 ? void 0 : _a.capabilities,
             });
-            this.updateToolsAfterServerModeResolved();
+            this.composePendingToolsForClient();
             await this.resolveWidgets();
             const result = await sdkInitHandler(request);
-            result.instructions = getServerInstructions(this.serverMode);
+            // Tools are final here (composePendingToolsForClient ran above, applying the per-client
+            // blocklist), so tool presence is the ground truth for whether to advertise
+            // report-problem in the instructions.
+            result.instructions = getServerInstructions(this.serverMode, this.tools.has(HELPER_TOOLS.PROBLEM_REPORT));
             return result;
         });
     }
-    updateToolsAfterServerModeResolved() {
-        if (this.pendingToolsAfterModeResolved.length === 0)
+    /** True once the connecting client is known (set in the initialize handler, or hydrated by a
+     *  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;
+    }
+    /**
+     * Compose the tool list for the current connection: resolve mode-specific tools, then drop
+     * report-problem unless it is currently servable (see {@link isReportProblemServable}).
+     * report-problem is a default-injected tool (via tools_loader) rather than a category member,
+     * gated here by servability. Every other tool composes eagerly, so a recovery/rehydration load
+     * without an initialize still restores them. report-problem is withheld until the client is known
+     * and re-added by the initialize flush. Used by every input-driven load path and the flush.
+     * (loadActorsAsTools upserts actor tools directly; actor tools are never gated, so they need no
+     * filtering.)
+     */
+    composeToolsForClient(input, actorTools) {
+        const tools = getToolsForServerMode(input, actorTools, this.serverMode);
+        if (this.isReportProblemServable())
+            return tools;
+        return tools.filter((tool) => tool.name !== HELPER_TOOLS.PROBLEM_REPORT);
+    }
+    /**
+     * Whether report-problem may be served on this connection right now:
+     * - Its only function is forwarding submissions via telemetry, so it is never servable when
+     *   telemetry is disabled (it would just fake an acknowledgement into the void).
+     * - It cannot be judged until the connecting client is known, so it is withheld until then;
+     *   the initialize flush re-composes and adds it if the client allows.
+     * Every other tool is unconditionally servable, so recovery loads compose them eagerly and they
+     * survive a load that never sees an initialize.
+     */
+    isReportProblemServable() {
+        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;
-        const tools = this.pendingToolsAfterModeResolved.flatMap(({ input, actorTools }) => getToolsForServerMode(input, actorTools, this.serverMode));
-        this.pendingToolsAfterModeResolved = [];
-        // Notify after the flush so shared-state handlers (e.g. Redis recovery) see
-        // the final tool set, including mode-specific helpers added here. Pre-init,
-        // `loadToolsByName` may have fired `upsertTools(actorTools, true)` with actor
-        // tools only (helpers still queued), and `loadToolsFromUrl` / `loadToolsFromInput`
-        // don't notify at all — this call reconciles both paths to the complete set.
+        const tools = this.pendingToolsUntilClientKnown.flatMap(({ input, actorTools }) => this.composeToolsForClient(input, actorTools));
+        this.pendingToolsUntilClientKnown = [];
+        // Notify after the flush so shared-state handlers (e.g. Redis recovery) see the final tool
+        // set. Load paths already upserted the client-agnostic tools pre-init; re-upserting is
+        // idempotent, and this pass adds the client-gated tools (e.g. report-problem) now that the
+        // client is known, reconciling shared state to the complete set.
         if (tools.length > 0)
             this.upsertTools(tools, true);
     }
@@ -408,6 +485,31 @@ export class ActorsMcpServer {
     listAllToolNames() {
         return [...this.listInternalToolNames(), ...this.listActorToolNames(), ...this.listActorMcpServerToolIds()];
     }
+    /**
+     * Buffer-or-compose gate shared by the actor-tools loaders. If the server mode isn't resolved
+     * yet ('auto' before initialize), queue the whole source for `composePendingToolsForClient` and
+     * (if non-empty) upsert the mode-agnostic actor tools immediately with the given `shouldNotify`.
+     * Once the mode is resolved, compose the client-specific set via `composeToolsForClient` (which
+     * withholds report-problem until the client is known) and upsert it; if the client still isn't
+     * known, queue the source so the initialize flush re-composes and adds the client-gated tools.
+     *
+     * Callers pass different `shouldNotify` values: `loadToolsByName` forwards `actorTools.length > 0`
+     * (notify only when actor tools were fetched), while `loadToolsFromUrl` and `loadToolsFromInput`
+     * pass `false` and defer to the post-initialize reconcile. See `composePendingToolsForClient`.
+     */
+    registerFetchedActorTools(input, actorTools, shouldNotify) {
+        if (!this.serverModeResolved) {
+            this.pendingToolsUntilClientKnown.push({ input, actorTools });
+            if (actorTools.length > 0)
+                this.upsertTools(actorTools, shouldNotify);
+            return;
+        }
+        const tools = this.composeToolsForClient(input, actorTools);
+        if (tools.length > 0)
+            this.upsertTools(tools, shouldNotify);
+        if (!this.clientKnown)
+            this.pendingToolsUntilClientKnown.push({ input, actorTools });
+    }
     /**
      * Loads missing toolNames from a provided list of tool names.
      * Skips toolNames that are already loaded and loads only the missing ones.
@@ -424,16 +526,7 @@ export class ActorsMcpServer {
             actorStore: this.actorStore,
             paymentProvider: this.options.paymentProvider,
         });
-        if (!this.serverModeResolved) {
-            this.pendingToolsAfterModeResolved.push({ input: restoreInput, actorTools });
-            if (actorTools.length > 0)
-                this.upsertTools(actorTools, true);
-            return;
-        }
-        const toolsToLoad = getToolsForServerMode(restoreInput, actorTools, this.serverMode);
-        if (toolsToLoad.length > 0) {
-            this.upsertTools(toolsToLoad, actorTools.length > 0);
-        }
+        this.registerFetchedActorTools(restoreInput, actorTools, actorTools.length > 0);
     }
     /**
      * Load Actors as tools, upsert successes into the server, and return both the tool
@@ -458,24 +551,14 @@ export class ActorsMcpServer {
             actorStore: this.actorStore,
             paymentProvider: this.options.paymentProvider,
         });
-        if (!this.serverModeResolved) {
-            this.pendingToolsAfterModeResolved.push({ input, actorTools });
-            if (actorTools.length > 0) {
-                log.debug('Loading actor tools from query parameters before mode resolution');
-                this.upsertTools(actorTools, false);
-            }
-            return;
-        }
-        const tools = getToolsForServerMode(input, actorTools, this.serverMode);
-        if (tools.length > 0) {
-            log.debug('Loading tools from query parameters');
-            this.upsertTools(tools, false);
-        }
+        log.debug('Loading tools from query parameters');
+        this.registerFetchedActorTools(input, actorTools, false);
     }
     /**
-     * Two-phase: getActors (async, mode-agnostic Apify fetch) then getToolsForServerMode
-     * (sync, mode-dependent compose). When mode is unresolved, queue actorTools and let
-     * the initialize handler compose them later.
+     * Two-phase: getActors (async, client-agnostic Apify fetch) then composeToolsForClient
+     * (sync compose + servability filter). If the mode isn't resolved yet ('auto' before initialize)
+     * the whole source is queued for the flush. Otherwise tools compose immediately; client-gated
+     * tools are withheld until the client is known, and the source is queued so the flush adds them.
      *
      * Don't move the getActors await into the initialize handler — clients time out
      * waiting for InitializeResult. The queue buffers already-fetched data, not network
@@ -486,15 +569,7 @@ export class ActorsMcpServer {
             actorStore: this.actorStore,
             paymentProvider: this.options.paymentProvider,
         });
-        if (!this.serverModeResolved) {
-            this.pendingToolsAfterModeResolved.push({ input, actorTools });
-            if (actorTools.length > 0)
-                this.upsertTools(actorTools);
-            return;
-        }
-        const tools = getToolsForServerMode(input, actorTools, this.serverMode);
-        if (tools.length > 0)
-            this.upsertTools(tools);
+        this.registerFetchedActorTools(input, actorTools, false);
     }
     /** Delete tools from the server and notify the handler.
      */
@@ -518,6 +593,9 @@ export class ActorsMcpServer {
      * @returns Array of added/updated tool wrappers
      */
     upsertTools(tools, shouldNotifyToolsChangedHandler = false) {
+        // Client gating (e.g. hiding report-problem from Anthropic surfaces) is applied earlier, in
+        // composeToolsForClient — the single compose choke point where the client is known. Do not
+        // filter here: this is a low-level commit point reached before the client is known too.
         for (const tool of tools) {
             const stored = this.options.paymentProvider ? this.options.paymentProvider.decorateToolSchema(tool) : tool;
             this.tools.set(stored.name, stored);
@@ -642,6 +720,18 @@ export class ActorsMcpServer {
             };
         });
     }
+    /**
+     * Fetches a task by ID, softFail-logging and throwing a client-facing McpError if it doesn't exist.
+     */
+    async getTaskOrThrow(taskId, mcpSessionId, logTag) {
+        const task = await this.taskStore.getTask(taskId, mcpSessionId);
+        if (!task) {
+            // Client error (invalid/unknown taskId) — softFail to avoid polluting error logs.
+            log.softFail(`[${logTag}] Task not found`, { taskId, mcpSessionId, statusCode: 404 });
+            throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" not found`);
+        }
+        return task;
+    }
     /**
      * Sets up MCP request handlers for long-running tasks.
      */
@@ -665,12 +755,7 @@ export class ActorsMcpServer {
             const { taskId } = params;
             const mcpSessionId = (_a = params._meta) === null || _a === void 0 ? void 0 : _a.mcpSessionId;
             log.debug('[GetTaskRequestSchema] Getting task status', { taskId, mcpSessionId });
-            const task = await this.taskStore.getTask(taskId, mcpSessionId);
-            if (task)
-                return task;
-            // Client error (invalid/unknown taskId) — softFail to avoid polluting error logs.
-            log.softFail('[GetTaskRequestSchema] Task not found', { taskId, mcpSessionId, statusCode: 404 });
-            throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" not found`);
+            return await this.getTaskOrThrow(taskId, mcpSessionId, 'GetTaskRequestSchema');
         });
         // Get task result payload
         this.server.setRequestHandler(GetTaskPayloadRequestSchema, async (request) => {
@@ -680,12 +765,7 @@ export class ActorsMcpServer {
             const { taskId } = params;
             const mcpSessionId = (_a = params._meta) === null || _a === void 0 ? void 0 : _a.mcpSessionId;
             log.debug('[GetTaskPayloadRequestSchema] Getting task result', { taskId, mcpSessionId });
-            const task = await this.taskStore.getTask(taskId, mcpSessionId);
-            if (!task) {
-                // Client error (invalid/unknown taskId) — softFail to avoid polluting error logs.
-                log.softFail('[GetTaskPayloadRequestSchema] Task not found', { taskId, mcpSessionId, statusCode: 404 });
-                throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" not found`);
-            }
+            const task = await this.getTaskOrThrow(taskId, mcpSessionId, 'GetTaskPayloadRequestSchema');
             if (task.status !== 'completed' && task.status !== 'failed') {
                 throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" is not completed yet. Current status: ${task.status}`);
             }
@@ -707,12 +787,7 @@ export class ActorsMcpServer {
             const { taskId } = params;
             const mcpSessionId = (_a = params._meta) === null || _a === void 0 ? void 0 : _a.mcpSessionId;
             log.debug('[CancelTaskRequestSchema] Cancelling task', { taskId, mcpSessionId });
-            const task = await this.taskStore.getTask(taskId, mcpSessionId);
-            if (!task) {
-                // Client error (invalid/unknown taskId) — softFail to avoid polluting error logs.
-                log.softFail('[CancelTaskRequestSchema] Task not found', { taskId, mcpSessionId, statusCode: 404 });
-                throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" not found`);
-            }
+            const task = await this.getTaskOrThrow(taskId, mcpSessionId, 'CancelTaskRequestSchema');
             if (task.status === 'completed' || task.status === 'failed' || task.status === 'cancelled') {
                 // Client error (cancel on terminal task) — softFail to avoid polluting error logs.
                 log.softFail('[CancelTaskRequestSchema] Task already in terminal state', {
@@ -772,11 +847,19 @@ export class ActorsMcpServer {
             let callDiagnostics = {};
             let shouldTrackTelemetry = true;
             let resolvedToolName = name;
+            // Set only on the pre-flight task path — the one task-mode flow whose telemetry rides
+            // 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.
             let toolResult = null;
             const captureResult = (r) => {
-                toolResult = r;
-                return 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 = this.withReportProblemNudge(r, resolvedToolName, callDiagnostics.failure_category, callDiagnostics.failure_http_status);
+                toolResult = augmented;
+                return augmented;
             };
             const failInvalidParams = async (message, details, logFields) => {
                 toolStatus = TOOL_STATUS.SOFT_FAIL;
@@ -918,6 +1001,50 @@ export class ActorsMcpServer {
                         toolName: tool.name,
                         mcpSessionId,
                     });
+                    // Pre-flight failure is already known — the outcome needs no work. Resolve the
+                    // task synchronously: store the failure as the terminal `completed` result and emit
+                    // exactly one `completed` status notification (no `updateTaskStatus('working')`, so no
+                    // `working` notification). Standby rejection wins over the generic payment-required
+                    // short-circuit, matching the sync path's precedence. Telemetry rides the handler's
+                    // outer `finally` (shouldTrackTelemetry stays true), firing once with the sync-path
+                    // properties plus the taskId on the log line.
+                    const preflightResult = standbyRejection !== null && standbyRejection !== void 0 ? standbyRejection : paymentRequiredResult;
+                    if (preflightResult) {
+                        const outcome = buildPreflightFailureOutcome(standbyRejection, paymentRequiredResult, actorName, actorId);
+                        toolStatus = outcome.toolStatus;
+                        callDiagnostics = outcome.callDiagnostics;
+                        preflightTaskId = task.taskId;
+                        try {
+                            await storeTaskResultOrSkipIfExpired(this.taskStore, tool.name, task.taskId, 'completed', outcome.result, mcpSessionId);
+                        }
+                        catch (error) {
+                            // A store failure (not expiry) would otherwise fall through to the generic
+                            // catch and return a task-less tool result the client rejects as a
+                            // 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.
+                            toolStatus = TOOL_STATUS.FAILED;
+                            callDiagnostics = {
+                                failure_category: FAILURE_CATEGORY.INTERNAL_ERROR,
+                                ...buildActorFields(actorName, actorId),
+                            };
+                            throw new McpError(ErrorCode.InternalError, `Failed to store the pre-flight result for task "${task.taskId}": ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                        // Defer so the client sees the CreateTaskResult (and learns the taskId) before
+                        // the terminal status notification — the async path's post-response ordering.
+                        // emitTaskStatusNotification never throws and no-ops if the task expired.
+                        setImmediate(() => {
+                            void emitTaskStatusNotification(task.taskId, mcpSessionId, this.taskStore, this.server);
+                        });
+                        captureResult(outcome.result);
+                        // 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
+                        // `working` fallback would contradict the tasks/get 404 the client sees next.
+                        return { task: { ...task, status: 'completed' } };
+                    }
                     // Execute the tool asynchronously and update task status
                     setImmediate(() => {
                         this.executeToolAndUpdateTask({
@@ -925,8 +1052,6 @@ export class ActorsMcpServer {
                             tool,
                             toolArgs: toolArgs,
                             logSafeArgs,
-                            standbyRejection,
-                            paymentRequiredResult,
                             apifyClient: apifyClient,
                             apifyToken,
                             progressToken,
@@ -943,25 +1068,14 @@ export class ActorsMcpServer {
                     shouldTrackTelemetry = false;
                     return { task };
                 }
-                // Sync path: standby rejection wins over the generic payment-required short-circuit
-                // so the agent gets the precise reason instead of a 402.
-                if (standbyRejection) {
-                    toolStatus = TOOL_STATUS.SOFT_FAIL;
-                    callDiagnostics = {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        ...buildActorFields(actorName, actorId),
-                    };
-                    return captureResult(standbyRejection);
-                }
-                // Check payment validation (already computed by prepareToolCallContext)
-                if (paymentRequiredResult) {
-                    toolStatus = TOOL_STATUS.SOFT_FAIL;
-                    callDiagnostics = {
-                        failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                        failure_http_status: 402,
-                        ...buildActorFields(actorName, actorId),
-                    };
-                    return captureResult(paymentRequiredResult);
+                // 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);
                 }
                 // Handle internal tool
                 if (tool.type === TOOL_TYPE.INTERNAL) {
@@ -984,9 +1098,7 @@ export class ActorsMcpServer {
                             mcpSessionId,
                         }));
                         // Extract diagnostics and strip internal fields from res before returning to client.
-                        const diag = extractToolTelemetry(res, actorName, actorId);
-                        toolStatus = diag.toolStatus;
-                        callDiagnostics = { ...callDiagnostics, ...diag.callDiagnostics };
+                        ({ toolStatus, callDiagnostics } = applyToolTelemetry(res, actorName, actorId, callDiagnostics));
                         return captureResult(res);
                     }
                     finally {
@@ -1097,6 +1209,10 @@ export class ActorsMcpServer {
                             // 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 {
@@ -1186,6 +1302,7 @@ export class ActorsMcpServer {
                         callDiagnostics,
                         args,
                         result: toolResult,
+                        taskId: preflightTaskId,
                     });
                 }
             }
@@ -1243,6 +1360,13 @@ export class ActorsMcpServer {
                 ...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
@@ -1259,7 +1383,7 @@ export class ActorsMcpServer {
      * @param params.mcpSessionId - MCP session ID for telemetry
      */
     async executeToolAndUpdateTask(params) {
-        const { taskId, tool, toolArgs, logSafeArgs, standbyRejection, paymentRequiredResult, apifyClient, apifyToken, progressToken, extra, mcpSessionId, actorName, actorId, } = 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) };
@@ -1331,25 +1455,6 @@ export class ActorsMcpServer {
             await emitTaskStatusNotification(taskId, mcpSessionId, this.taskStore, this.server);
             // Execute the tool and get the result
             let result = {};
-            // Mirror the sync-path ordering: standby rejection wins over the generic 402 so the
-            // stored task result carries the precise reason the agent should act on.
-            if (standbyRejection) {
-                toolStatus = TOOL_STATUS.SOFT_FAIL;
-                callDiagnostics = {
-                    failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                    ...buildActorFields(actorName, actorId),
-                };
-                result = standbyRejection;
-            }
-            else if (paymentRequiredResult) {
-                toolStatus = TOOL_STATUS.SOFT_FAIL;
-                callDiagnostics = {
-                    failure_category: FAILURE_CATEGORY.INVALID_INPUT,
-                    failure_http_status: 402,
-                    ...buildActorFields(actorName, actorId),
-                };
-                result = paymentRequiredResult;
-            }
             // 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.
@@ -1378,9 +1483,7 @@ export class ActorsMcpServer {
                         mcpSessionId,
                         taskMode: true,
                     }));
-                    const diag = extractToolTelemetry(res, actorName, actorId);
-                    toolStatus = diag.toolStatus;
-                    callDiagnostics = { ...callDiagnostics, ...diag.callDiagnostics };
+                    ({ toolStatus, callDiagnostics } = applyToolTelemetry(res, actorName, actorId, callDiagnostics));
                     result = res;
                 }
                 finally {
@@ -1418,6 +1521,9 @@ export class ActorsMcpServer {
                         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;
                     }
                 }
@@ -1430,6 +1536,9 @@ export class ActorsMcpServer {
             // 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,
@@ -1542,7 +1651,11 @@ export class ActorsMcpServer {
                 taskId,
                 mcpSessionId,
             });
-            const failedResult = {
+            // 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',
@@ -1551,7 +1664,7 @@ export class ActorsMcpServer {
                 ],
                 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);