feat: Modify get-actor-run - add waitSec and progress (#823)

`get-actor-run` returns the canonical run shape (status, storages,
stats, summary, nextStep) across all 8 Apify states. Text content
carries `summary \n nextStep`; structuredContent has the full shape — no
inlined items or record bodies.

Adds `waitSecs` (0–45, default 30) and emits `notifications/progress`
during the wait when `_meta.progressToken` is supplied.
`get-actor-run-widget` uses `waitSecs=0` so initial render is
non-blocking; widget self-polls.

`SUCCEEDED` with `itemCount=0` runs a one-item probe with one retry to
absorb Apify's ~5s pagination-counter lag — no false "no output" on a
run that did write items. KV shows up in `summary` only; never
recommended as `nextStep`, since it rarely carries real output (mostly
SDK state).

Follow-up PR #825 replaces `call-actor`'s `async` flag with the same
`waitSecs` and reshapes `storages` to a plural alias-map. Stacks on this
branch and lands together.

**Follow-up #847** — consolidate duplicated MCP server test fixtures
across three test files (surfaced during review); left out per "one
thing per change".

## Why this PR is bulky

Splitting the pieces below would leave master in a broken half-state:

- New shared module `src/tools/core/actor_run_response.ts` centralizes
the canonical shape, 8 status templates, wait+progress loop,
lag-fallback probe, and abort race. #825 (`call-actor` v4) reuses every
helper.
- Test coverage for the new contract — shape, 8 templates,
wait/progress, abort, lag-fallback.
- Widget UI in `src/web/src/pages/ActorRun/ActorRun.tsx` switched to a
`get-dataset-items` preview fetch with its own polling cadence — v4
dropped inlined items, so the UI is broken until the server stops
inlining.
- Spec, structured-output schema, tool-loader auto-inject, and widget
dev stub round out the v4 contract across modes.

Closes #822

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Jakub Kopecký <themq37@gmail.com>

Author: 3 people

CLAUDE.md

@@ -66,6 +66,7 @@ Breaking changes must be coordinated; check whether updates are needed in `apify
 - **Follow [CONTRIBUTING.md](./CONTRIBUTING.md) for all naming and coding standards.** It is the single source of truth for naming rules (function verbs, boolean prefixes, type suffixes, enumerations, file names, etc.), string formatting, parameters, error handling, and anti-patterns. Read it before writing code.
 - **Validate tool inputs with Zod.** No ad-hoc shape checks.
 - **Reference tool names via the `HelperTools` enum**, not hardcoded strings (exception: integration tests).
+- **Apps vs default mode**: only `*-widget` tools differ between modes. All non-widget tools (`call-actor`, `get-actor-run`, direct actor tools, `search-actors`, `fetch-actor-details`) share a single implementation across modes.
 - Always follow the latest [MCP spec](https://modelcontextprotocol.io/specification/2025-11-25) and [MCP Apps spec](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
 
 ## Further reading

res/call_actor_redesign_v4.md

@@ -65,13 +65,11 @@ import { createResourceService } from '../resources/resource_service.js';
 import type { AvailableWidget } from '../resources/widgets.js';
 import { resolveAvailableWidgets } from '../resources/widgets.js';
 import { getTelemetryEnv, trackToolCall } from '../telemetry.js';
-import { appsActorExecutor } from '../tools/apps/actor_executor.js';
+import { actorExecutor } from '../tools/actor_executor.js';
 import { buildPermissionApprovalResponse, isPermissionApprovalError } from '../tools/core/call_actor_common.js';
-import { defaultActorExecutor } from '../tools/default/actor_executor.js';
 import { getActorsAsTools } from '../tools/index.js';
 import { decodeDotPropertyNames, legacyToolNameToNew } from '../tools/utils.js';
 import type {
-    ActorExecutor,
     ActorsMcpServerOptions,
     ActorStore,
     ApifyRequestParams,
@@ -103,12 +101,6 @@ import { connectMCPClient } from './client.js';
 import { EXTERNAL_TOOL_CALL_TIMEOUT_MSEC, LOG_LEVEL_MAP } from './const.js';
 import { createTaskCancellationWatcher, isTaskCancelled, parseInputParamsFromUrl } from './utils.js';
 
-/** Mode → actor executor. Add new modes here. */
-const actorExecutorsByMode: Record<ServerMode, ActorExecutor> = {
-    [ServerMode.DEFAULT]: defaultActorExecutor,
-    [ServerMode.APPS]: appsActorExecutor,
-};
-
 /**
  * Returns true when the initialize request advertises the MCP Apps UI extension
  * with the widget MIME type. Used to resolve `'auto'` server mode.
@@ -173,8 +165,6 @@ export class ActorsMcpServer {
      * client's capabilities are known. Effectively set-once per connection.
      */
     public serverMode: ServerMode;
-    /** Mode-specific executor for direct actor tools (`type: 'actor'`). Finalized with `serverMode`. */
-    private actorExecutor: ActorExecutor;
     /**
      * Raw option captured from `options.serverMode` (or the legacy `uiMode`). Re-resolved
      * inside the initialize handler when set to `'auto'`; explicit `'default'`/`'apps'`
@@ -227,7 +217,6 @@ export class ActorsMcpServer {
         // client capabilities are known (only for 'auto').
         this.serverMode = resolveServerMode(this.serverModeOption, false);
         this.serverModeResolved = this.serverModeOption !== 'auto';
-        this.actorExecutor = actorExecutorsByMode[this.serverMode];
 
         const { setupSigintHandler = true } = options;
         this.server = new Server(
@@ -324,7 +313,6 @@ export class ActorsMcpServer {
                 const resolved = resolveServerMode('auto', this.clientSupportsUi);
                 if (resolved !== this.serverMode) {
                     this.serverMode = resolved;
-                    this.actorExecutor = actorExecutorsByMode[this.serverMode];
                 }
                 this.serverModeResolved = true;
             }
@@ -1015,8 +1003,11 @@ export class ActorsMcpServer {
 
                 // Handle internal tool
                 if (tool.type === 'internal') {
-                    // Only create a progress tracker for call-actor tool
-                    const progressTracker = tool.name === 'call-actor'
+                    // Tools that may emit notifications/progress during a sync wait must be opted in here.
+                    // call-actor: emits during start+waitForFinish. get-actor-run: emits when waitSecs > 0.
+                    const progressTrackerOptIn = tool.name === HelperTools.ACTOR_CALL
+                        || tool.name === HelperTools.ACTOR_RUNS_GET;
+                    const progressTracker = progressTrackerOptIn
                         ? createProgressTracker(progressToken, extra.sendNotification)
                         : null;
 
@@ -1130,14 +1121,15 @@ export class ActorsMcpServer {
 
                     try {
                         log.info('Calling Actor', { toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
-                        const executorResult = await this.actorExecutor.executeActorTool({
+                        const executorResult = await actorExecutor.executeActorTool({
                             actorFullName: tool.actorFullName,
                             input: toolArgs!,
                             apifyClient: apifyClient!,
                             callOptions: { memory: tool.memoryMbytes },
                             progressTracker,
                             abortSignal: extra.signal,
                             mcpSessionId,
+                            datasetItemsSchema: tool.datasetItemsSchema,
                         });
 
                         if (!executorResult) {
@@ -1434,6 +1426,7 @@ export class ActorsMcpServer {
                         userRentedActorIds,
                         progressTracker,
                         mcpSessionId,
+                        taskMode: true,
                     }) as Record<string, unknown>;
 
                     const diag = extractToolTelemetry(res, actorName, actorId);
@@ -1453,14 +1446,16 @@ export class ActorsMcpServer {
 
                 try {
                     log.info('Calling Actor for task', { taskId, toolName: tool.name, actorName: tool.actorFullName, mcpSessionId, input: logSafeArgs });
-                    const executorResult = await this.actorExecutor.executeActorTool({
+                    const executorResult = await actorExecutor.executeActorTool({
                         actorFullName: tool.actorFullName,
                         input: toolArgs,
                         apifyClient,
                         callOptions: { memory: tool.memoryMbytes },
                         progressTracker,
                         abortSignal: cancelWatcher.signal,
                         mcpSessionId,
+                        datasetItemsSchema: tool.datasetItemsSchema,
+                        taskMode: true,
                     });
 
                     if (!executorResult) {

src/mcp/server.ts

@@ -14,7 +14,7 @@ import { loadToolsFromInput } from '../utils/tools_loader.js';
  * @param url The URL to process
  * @param apifyClient The Apify client instance
  * @param mode Server mode for tool variant resolution
- * @param actorStore
+ * @param actorStore Optional store used to enrich direct actor tools' outputSchema with per-Actor itemsSchema.
  */
 export async function processParamsGetTools(
     url: string,

src/mcp/utils.ts

@@ -0,0 +1,87 @@
+import log from '@apify/log';
+
+import type { ActorExecutionParams, ActorExecutionResult, ActorExecutor } from '../types.js';
+import { redactSkyfirePayId } from '../utils/logging.js';
+import { abortRunOnSignal, CALL_ACTOR_WAIT_SECS_DEFAULT, fetchActorRunData } from './core/actor_run_response.js';
+import { buildGetActorRunSuccessResponse } from './core/get_actor_run_common.js';
+
+/**
+ * Direct actor tool executor. Mode-agnostic — used in both default and apps modes.
+ * Returns the canonical `RunResponse` shape; dataset items are not inlined — the LLM
+ * follows `nextStep` to `get-dataset-items`.
+ *
+ * Wait contract matches `call-actor`: default 30 s, max 45, task mode waits until terminal.
+ */
+export const actorExecutor: ActorExecutor = {
+    async executeActorTool(params: ActorExecutionParams): Promise<ActorExecutionResult> {
+        const { actorFullName, apifyClient, mcpSessionId, abortSignal, progressTracker, taskMode } = params;
+        // Strip `waitSecs` from the Actor's input — it's an MCP-injected opt-in, not an
+        // Actor field — so `actor.start()` doesn't reject or silently pass it through.
+        const { waitSecs: argsWaitSecs, ...actorInput } = params.input as { waitSecs?: number } & Record<string, unknown>;
+        // Task mode waits until terminal; honoring waitSecs would let the task complete
+        // before the Actor produced output. Mirrors executeCallActor.
+        // AJV doesn't fill `default` values, so apply the 30 s default here when the LLM omits waitSecs.
+        const waitSecs = taskMode ? undefined : (argsWaitSecs ?? CALL_ACTOR_WAIT_SECS_DEFAULT);
+        const redactedInput = redactSkyfirePayId(params.input);
+
+        if (abortSignal?.aborted) {
+            log.info('Actor run aborted by client before start', {
+                actorName: actorFullName,
+                mcpSessionId,
+                input: redactedInput,
+            });
+            return null;
+        }
+
+        const actorRun = await apifyClient.actor(actorFullName).start(actorInput, params.callOptions);
+
+        log.debug('Started Actor run (direct actor tool)', {
+            actorName: actorFullName,
+            runId: actorRun.id,
+            mcpSessionId,
+            waitSecs,
+        });
+
+        if (abortSignal?.aborted) {
+            await abortRunOnSignal(actorRun.id, apifyClient);
+            log.info('Actor run aborted by client', {
+                actorName: actorFullName,
+                mcpSessionId,
+                runId: actorRun.id,
+                input: redactedInput,
+            });
+            return null;
+        }
+
+        const fetchResult = await fetchActorRunData({
+            runId: actorRun.id,
+            waitSecs,
+            actorName: actorFullName,
+            client: apifyClient,
+            progressTracker,
+            abortSignal,
+            mcpSessionId,
+            onAbort: abortRunOnSignal,
+        });
+
+        if ('aborted' in fetchResult) {
+            log.info('Actor run aborted by client', {
+                actorName: actorFullName,
+                mcpSessionId,
+                runId: actorRun.id,
+                input: redactedInput,
+            });
+            return null;
+        }
+        if ('error' in fetchResult) return fetchResult.error as ActorExecutionResult;
+
+        // Mirror the tool's declared `itemsSchema` into the runtime response so the response
+        // matches its outputSchema. Only direct actor tools know the row shape up front.
+        const dataset = fetchResult.result.structuredContent.storages?.datasets?.default;
+        if (dataset && params.datasetItemsSchema) {
+            dataset.itemsSchema = { type: 'object', properties: params.datasetItemsSchema };
+        }
+
+        return buildGetActorRunSuccessResponse({ ...fetchResult.result, widget: false }) as ActorExecutionResult;
+    },
+};

src/tools/actor_executor.ts

@@ -1,35 +1,25 @@
-import log from '@apify/log';
-
 import { HelperTools } from '../../const.js';
 import type { InternalToolArgs, ToolEntry } from '../../types.js';
-import { extractActorId } from '../../utils/tools.js';
 import {
-    buildCallActorDescription,
-    buildCallActorErrorResponse,
-    buildStartAsyncResponse,
+    buildCallActorAppsDescription,
     callActorAjvValidate,
     callActorInputSchema,
-    callActorPreExecute,
-    resolveAndValidateActor,
+    executeCallActor,
 } from '../core/call_actor_common.js';
-import { callActorOutputSchema } from '../structured_output_schemas.js';
+import { getActorRunOutputSchema } from '../structured_output_schemas.js';
 
-const CALL_ACTOR_APPS_DESCRIPTION = buildCallActorDescription({
-    actorGetDetailsTool: HelperTools.ACTOR_GET_DETAILS,
-    alwaysAsync: true,
-});
+const CALL_ACTOR_APPS_DESCRIPTION = buildCallActorAppsDescription();
 
 /**
  * Apps mode call-actor tool.
- * Always runs asynchronously — starts the run and returns immediately with runId.
  * Renders no widget; for a live progress UI, use the call-actor-widget sibling.
  */
 export const appsCallActor: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.ACTOR_CALL,
     description: CALL_ACTOR_APPS_DESCRIPTION,
     inputSchema: callActorInputSchema,
-    outputSchema: callActorOutputSchema,
+    outputSchema: getActorRunOutputSchema,
     ajvValidate: callActorAjvValidate,
     paymentRequired: true,
     annotations: {
@@ -39,52 +29,9 @@ export const appsCallActor: ToolEntry = Object.freeze({
         idempotentHint: false,
         openWorldHint: true,
     },
-    call: async (toolArgs: InternalToolArgs) => {
-        const preResult = await callActorPreExecute(toolArgs, { route: HelperTools.ACTOR_CALL });
-        if ('earlyResponse' in preResult) {
-            return preResult.earlyResponse;
-        }
-
-        const { parsed, baseActorName } = preResult;
-        const { input, callOptions } = parsed;
-
-        let resolvedActorId: string | undefined;
-        try {
-            const resolution = await resolveAndValidateActor({
-                actorName: baseActorName,
-                input: input as Record<string, unknown>,
-                toolArgs,
-            });
-            if ('error' in resolution) {
-                return resolution.error;
-            }
-
-            resolvedActorId = extractActorId(resolution.actor);
-            const { apifyClient } = toolArgs;
-
-            // Apps mode always runs asynchronously
-            const actorClient = apifyClient.actor(baseActorName);
-            const actorRun = await actorClient.start(input, callOptions);
-            log.debug('Started Actor run (async)', { actorName: baseActorName, runId: actorRun.id, mcpSessionId: toolArgs.mcpSessionId });
-            const response = buildStartAsyncResponse({
-                actorName: baseActorName,
-                actorRun,
-                input,
-                widget: false,
-            });
-            return {
-                ...response,
-                toolTelemetry: { actorId: resolvedActorId },
-            };
-        } catch (error) {
-            return buildCallActorErrorResponse({
-                actorName: baseActorName,
-                error,
-                actorId: resolvedActorId,
-                isAsync: true,
-                mcpSessionId: toolArgs.mcpSessionId,
-                actorGetDetailsTool: HelperTools.ACTOR_GET_DETAILS,
-            });
-        }
+    execution: {
+        // Support long-running tasks
+        taskSupport: 'optional',
     },
+    call: async (toolArgs: InternalToolArgs) => executeCallActor(toolArgs),
 } as const);