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

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';
@@ -156,7 +158,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 +169,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 +320,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 +329,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 +467,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 +508,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 +533,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 +551,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 +575,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 +702,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 +737,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 +747,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 +769,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', {
@@ -775,8 +832,12 @@ export class ActorsMcpServer {
             // 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;
@@ -984,9 +1045,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 +1156,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 {
@@ -1243,6 +1306,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
@@ -1378,9 +1448,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 +1486,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 +1501,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 +1616,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 +1629,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);