feat: Split get-actor-run into data + -widget tools (#734)

* feat: Split get-actor-run into data + -widget tools

Final step (6 of 6) of the #577 umbrella rollout. Mirrors the
decoupled-pattern recipe from #722 (fetch-actor-details), #723
(search-actors), and #724 (call-actor):

- get-actor-run is now mode-independent and data-only. No tool-level
  widget _meta in either mode; runs category entry is a plain ToolEntry
  instead of a mode map.
- New get-actor-run-widget (apps-only) renders the live progress widget.
  Input is strict: { runId } only. Tool- and response-level widget _meta
  (ui.resourceUri = ui://widget/actor-run.html). Reuses the shared
  buildGetActorRunSuccessResponse({ widget: true }) helper.
- buildGetActorRunSuccessResponse widget branch now also sets
  openai/widgetDescription on the response _meta, matching the other
  three widget tools.
- Apps server instructions: added the fourth disambiguation bullet
  pairing get-actor-run (silent data lookup) with get-actor-run-widget
  (live progress widget), using the same vocabulary as the existing
  three splits. WORKFLOW_RULES untouched — the "NEVER poll
  get-actor-run after call-actor-widget" rule is orthogonal.
- Deleted src/tools/apps/get_actor_run.ts; widget rendering now lives
  in the sibling tool rather than a mode toggle.

https://claude.ai/code/session_01SF9P6g91UrVMahn4bLsUNf

* chore: Address staff review findings post-split

- Drop stale rolling-rollout note from server-instructions header (split is now complete)
- Extend "no polling after widget" rule to also cover get-actor-run-widget
- Rename integration test to drop misleading "widget" label (it exercises the data tool)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: Remove paymentRequired flag from get-actor-run tools

* Update src/tools/core/get_actor_run_common.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update src/tools/apps/get_actor_run_widget.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* test: Add integration test for x402 _meta advertising on paid tools (#768)

Asserts that tools with paymentRequired: true advertise _meta.x402 with
the expected fields (scheme, network, asset, payTo, amount) when the
server runs in x402 payment mode, and that free tools do not.

Pins the expected paid set with a hardcoded list so silent drift (e.g.
a tool losing paymentRequired) is caught here. Tracks #766.

* feat: Add paymentRequired flag to get-actor-run tools and update documentation

* refactor: Skip tests for auto mode client capabilities and rename itemCount to totalItemCount

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Jakub Kopecký <themq37@gmail.com>

Author: 4 people

src/const.ts

@@ -31,6 +31,7 @@ export enum HelperTools {
     ACTOR_OUTPUT_GET = 'get-actor-output',
     ACTOR_RUNS_ABORT = 'abort-actor-run',
     ACTOR_RUNS_GET = 'get-actor-run',
+    ACTOR_RUNS_GET_WIDGET = 'get-actor-run-widget',
     ACTOR_RUNS_LOG = 'get-actor-log',
     ACTOR_RUN_LIST_GET = 'get-actor-run-list',
     DATASET_GET = 'get-dataset',

src/tools/apps/get_actor_run.ts

@@ -0,0 +1,78 @@
+import dedent from 'dedent';
+import { z } from 'zod';
+
+import { HelperTools } from '../../const.js';
+import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
+import type { InternalToolArgs, ToolEntry, ToolInputSchema } from '../../types.js';
+import { compileSchema } from '../../utils/ajv.js';
+import { logHttpError } from '../../utils/logging.js';
+import {
+    buildGetActorRunError,
+    buildGetActorRunSuccessResponse,
+    fetchActorRunData,
+} from '../core/get_actor_run_common.js';
+import { getActorRunOutputSchema } from '../structured_output_schemas.js';
+
+/**
+ * Widget-only input: `runId` only. In the normal tool path, AJV validation
+ * runs first and strips unknown keys at the boundary; `.strict()` mainly
+ * protects any bypass paths by rejecting stray keys before use here.
+ */
+const getActorRunWidgetArgsSchema = z.object({
+    runId: z.string()
+        .min(1)
+        .describe('The ID of the Actor run.'),
+}).strict();
+
+const GET_ACTOR_RUN_WIDGET_DESCRIPTION = dedent`
+    Render an interactive UI element (widget) showing live progress and status of an Actor run.
+
+    Use this tool ONLY when the user explicitly wants to see run progress visually
+    (e.g., "show progress for run y2h7sK3Wc", "display the status of that run").
+
+    For silent data lookups (run status, dataset IDs, stats, resource IDs), use
+    ${HelperTools.ACTOR_RUNS_GET} instead — it returns the same data without rendering a widget.
+
+    Input: the run ID only.
+`;
+
+export const getActorRunWidgetTool: ToolEntry = Object.freeze({
+    type: 'internal',
+    name: HelperTools.ACTOR_RUNS_GET_WIDGET,
+    description: GET_ACTOR_RUN_WIDGET_DESCRIPTION,
+    inputSchema: z.toJSONSchema(getActorRunWidgetArgsSchema) as ToolInputSchema,
+    outputSchema: getActorRunOutputSchema,
+    ajvValidate: compileSchema(z.toJSONSchema(getActorRunWidgetArgsSchema)),
+    paymentRequired: true,
+    _meta: {
+        ...getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta,
+    },
+    annotations: {
+        title: 'Get Actor run (widget)',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    call: async (toolArgs: InternalToolArgs) => {
+        const { args, apifyClient: client, mcpSessionId } = toolArgs;
+        const parsed = getActorRunWidgetArgsSchema.parse(args);
+
+        try {
+            const fetchResult = await fetchActorRunData({
+                runId: parsed.runId,
+                client,
+                mcpSessionId,
+            });
+
+            if ('error' in fetchResult) {
+                return fetchResult.error;
+            }
+
+            return buildGetActorRunSuccessResponse({ ...fetchResult.result, widget: true });
+        } catch (error) {
+            logHttpError(error, 'Failed to get Actor run (widget)', { runId: parsed.runId });
+            return buildGetActorRunError(parsed.runId, error);
+        }
+    },
+} as const);

src/tools/apps/get_actor_run_widget.ts

@@ -18,7 +18,7 @@ import { ServerMode } from '../types.js';
 import { appsCallActor } from './apps/call_actor.js';
 import { appsCallActorWidget } from './apps/call_actor_widget.js';
 import { fetchActorDetailsWidgetTool } from './apps/fetch_actor_details_widget.js';
-import { appsGetActorRun } from './apps/get_actor_run.js';
+import { getActorRunWidgetTool } from './apps/get_actor_run_widget.js';
 import { searchActorsWidgetTool } from './apps/search_actors_widget.js';
 import { abortActorRun } from './common/abort_actor_run.js';
 import { addTool } from './common/add_actor.js';
@@ -76,13 +76,14 @@ export const toolCategories = {
         { apps: searchActorsWidgetTool },
         { apps: fetchActorDetailsWidgetTool },
         { apps: appsCallActorWidget },
+        { apps: getActorRunWidgetTool },
     ],
     docs: [
         searchApifyDocsTool,
         fetchApifyDocsTool,
     ],
     runs: [
-        { default: defaultGetActorRun, apps: appsGetActorRun },
+        defaultGetActorRun,
         getUserRunsList,
         getActorRunLog,
         abortActorRun,

src/tools/categories.ts

@@ -13,7 +13,7 @@ import { generateSchemaFromItems } from '../../utils/schema_generation.js';
 import { getActorRunOutputSchema } from '../structured_output_schemas.js';
 
 /**
- * Zod schema for get-actor-run arguments — shared between default and apps variants.
+ * Zod schema for get-actor-run arguments — shared between default and widget variants.
  */
 export const getActorRunArgs = z.object({
     runId: z.string()
@@ -27,15 +27,17 @@ The results will include run metadata (status, timestamps), performance stats, a
 USAGE:
 - Use when the user asks about a specific run's status or details.
 - Use to check the status of a run started with call-actor (e.g., before fetching output).
-- If you used call-actor-widget and a widget was rendered, do not poll get-actor-run; the widget handles status.
+- If a visual progress widget is available in this session, prefer that tool for UI rendering.
+- Returns pure data with no UI.
 
 USAGE EXAMPLES:
 - user_input: Show details of run y2h7sK3Wc (where y2h7sK3Wc is an existing run)
 - user_input: What is the datasetId for run y2h7sK3Wc?`;
 
 /**
  * Shared tool metadata for get-actor-run — everything except the `call` handler.
- * Used by both default and apps variants.
+ * Mode-independent, data-only. No widget _meta here; the widget variant in
+ * `src/tools/apps/get_actor_run_widget.ts` owns UI rendering.
  */
 export const getActorRunMetadata: Omit<HelperTool, 'call'> = {
     type: 'internal',
@@ -45,10 +47,6 @@ export const getActorRunMetadata: Omit<HelperTool, 'call'> = {
     outputSchema: getActorRunOutputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getActorRunArgs)),
     paymentRequired: true,
-    // openai/* and ui keys are stripped in non-apps mode by stripWidgetMeta() in src/utils/tools.ts
-    _meta: {
-        ...getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta,
-    },
     annotations: {
         title: 'Get Actor run',
         readOnlyHint: true,
@@ -125,6 +123,7 @@ export function buildGetActorRunSuccessResponse(
         _meta: {
             ...(getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta ?? {}),
             ...(buildUsageMeta(run) ?? {}),
+            'openai/widgetDescription': `Actor run progress for ${structuredContent.actorName ?? structuredContent.runId}`,
         },
     });
 }

src/tools/core/get_actor_run_common.ts

@@ -5,10 +5,6 @@
  * only when the resolved server mode is `'apps'`. Default-mode clients never
  * see widget tool names like `search-actors-widget` or `fetch-actor-details-widget`,
  * avoiding hallucinated calls to tools absent from `tools/list`.
- *
- * Note: the `-widget` suffix split is rolling out per-tool. `fetch-actor-details`,
- * `search-actors`, and `call-actor` are already split; `get-actor-run` still renders
- * a widget on its base name until its own split lands.
  */
 
 import { HelperTools, RAG_WEB_BROWSER } from '../../const.js';
@@ -52,7 +48,7 @@ ${isApps ? `
 ## Widget workflow (applies when tool responses include widget metadata)
 Some clients render widget-backed Actor tools: the response includes a live UI that automatically polls run status. When a widget is rendered, follow-up status polling by the model is a forbidden duplicate.
 
-- **Never call \`${HelperTools.ACTOR_RUNS_GET}\` after \`${HelperTools.ACTOR_CALL_WIDGET}\`.** The widget renders live progress and polls itself — stop after the widget response and defer to it for run status.
+- **Never call \`${HelperTools.ACTOR_RUNS_GET}\` or \`${HelperTools.ACTOR_RUNS_GET_WIDGET}\` after \`${HelperTools.ACTOR_CALL_WIDGET}\` or \`${HelperTools.ACTOR_RUNS_GET_WIDGET}\`.** Both widgets render live progress and poll themselves — stop after the widget response and defer to it for run status. Re-rendering the same run via \`${HelperTools.ACTOR_RUNS_GET_WIDGET}\` is a duplicate.
 - Polling \`${HelperTools.ACTOR_RUNS_GET}\` after \`${HelperTools.ACTOR_CALL}\` (the silent async variant, no widget) is fine — that tool renders no UI, so polling is expected when you need the run status.
 ` : ''}
 ## Tool dependencies and disambiguation
@@ -76,6 +72,7 @@ ${isApps ? `- **Data vs widget Actor tools (when the client supports widgets):**
   - \`${HelperTools.STORE_SEARCH}\` is a silent data lookup (Actor list for name resolution) with no UI; \`${HelperTools.STORE_SEARCH_WIDGET}\` renders an interactive UI element (widget) with Actor search results for the user to browse — use it only when the user explicitly asks to search or discover Actors.
   - \`${HelperTools.ACTOR_GET_DETAILS}\` is a silent data lookup (input schema, README, metadata) with no UI; \`${HelperTools.ACTOR_GET_DETAILS_WIDGET}\` renders an interactive UI element (widget) with Actor details — use it only when the user explicitly asks to see or browse the Actor.
   - \`${HelperTools.ACTOR_CALL}\` is a silent async start (returns runId, no UI); \`${HelperTools.ACTOR_CALL_WIDGET}\` renders an interactive UI element (widget) that tracks live Actor run progress — use it only when the user explicitly asks to see progress.
+  - \`${HelperTools.ACTOR_RUNS_GET}\` is a silent data lookup (run status, dataset IDs, stats) with no UI; \`${HelperTools.ACTOR_RUNS_GET_WIDGET}\` renders an interactive UI element (widget) showing live run progress for the user — use it only when the user explicitly asks to see run progress.
   - When the next step is running an Actor, prefer silent lookups (\`${HelperTools.STORE_SEARCH}\`, \`${HelperTools.ACTOR_GET_DETAILS}\`) over widget-backed variants.
 ` : ''}- **\`${HelperTools.STORE_SEARCH}\` vs ${RAG_WEB_BROWSER}:**
   \`${HelperTools.STORE_SEARCH}\` finds robust and reliable Actors for specific websites; ${RAG_WEB_BROWSER} is a general and versatile web scraping tool.

src/utils/server-instructions/index.ts

@@ -2536,7 +2536,10 @@ export function createIntegrationTestsSuite(
             await client.close();
         });
 
-        it('auto mode: client advertising UI capability receives apps-mode tools with widget metadata', async () => {
+        // TODO: re-enable when auto-detect is re-enabled in resolveServerMode (src/types.ts).
+        // Currently 'auto' resolves to DEFAULT regardless of client UI capability, so these
+        // tests cannot exercise capability-driven mode resolution.
+        it.skip('auto mode: client advertising UI capability receives apps-mode tools with widget metadata', async () => {
             // serverMode omitted → server defaults to 'auto'; client sends UI capability → server resolves to 'apps'
             client = await createClientFn({
                 clientCapabilities: {
@@ -2550,7 +2553,7 @@ export function createIntegrationTestsSuite(
             await client.close();
         });
 
-        it('auto mode: client without UI capability receives default-mode tools without widget metadata', async () => {
+        it.skip('auto mode: client without UI capability receives default-mode tools without widget metadata', async () => {
             // serverMode omitted → server defaults to 'auto'; client sends no UI capability → server resolves to 'default'
             client = await createClientFn();
             const tools = await client.listTools();
@@ -2612,6 +2615,61 @@ export function createIntegrationTestsSuite(
             },
         );
 
+        // x402 payment mode only works with Streamable-HTTP transport (requires HTTP headers).
+        it.runIf(options.transport === 'streamable-http')(
+            'should advertise x402 metadata on all paymentRequired tools when x402 payment is enabled',
+            async () => {
+                // Hardcoded list of tools expected to advertise _meta.x402 (i.e. paymentRequired: true).
+                // Kept independent of any production constant so this test pins the expected paid set
+                // and any silent drift (e.g. a tool losing paymentRequired) is caught here.
+                const paidToolNames = [
+                    HelperTools.ACTOR_CALL,
+                    HelperTools.ACTOR_OUTPUT_GET,
+                    HelperTools.ACTOR_RUNS_GET,
+                    HelperTools.ACTOR_RUNS_LOG,
+                    HelperTools.ACTOR_RUNS_ABORT,
+                    HelperTools.DATASET_GET,
+                    HelperTools.DATASET_GET_ITEMS,
+                    HelperTools.DATASET_SCHEMA_GET,
+                    HelperTools.KEY_VALUE_STORE_GET,
+                    HelperTools.KEY_VALUE_STORE_KEYS_GET,
+                    HelperTools.KEY_VALUE_STORE_RECORD_GET,
+                ];
+                const freeToolNames = [HelperTools.STORE_SEARCH, HelperTools.DOCS_SEARCH];
+
+                client = await createClientFn({
+                    payment: 'x402',
+                    tools: [...paidToolNames, ...freeToolNames],
+                });
+
+                const toolsList = await client.listTools();
+
+                // Positive: paid tools advertise _meta.x402 with the expected fields.
+                for (const toolName of paidToolNames) {
+                    const tool = toolsList.tools.find((t) => t.name === toolName);
+                    expect(tool, `Tool "${toolName}" should exist in the tools list`).toBeDefined();
+
+                    const x402 = tool?._meta?.x402 as Record<string, unknown> | undefined;
+                    expect(x402, `Tool "${toolName}" should advertise _meta.x402`).toBeDefined();
+                    expect(x402?.paymentRequired, `Tool "${toolName}" x402.paymentRequired should be true`).toBe(true);
+
+                    for (const field of ['scheme', 'network', 'asset', 'payTo', 'amount'] as const) {
+                        expect(x402?.[field], `Tool "${toolName}" should advertise x402.${field}`).toBeDefined();
+                    }
+                }
+
+                // Negative: free tools must not advertise _meta.x402.
+                for (const toolName of freeToolNames) {
+                    const tool = toolsList.tools.find((t) => t.name === toolName);
+                    expect(tool, `Tool "${toolName}" should exist in the tools list`).toBeDefined();
+                    const meta = tool?._meta as Record<string, unknown> | undefined;
+                    expect(meta?.x402, `Tool "${toolName}" should not advertise _meta.x402`).toBeUndefined();
+                }
+
+                await client.close();
+            },
+        );
+
         // x402 payment mode only works with Streamable-HTTP transport (requires HTTP headers).
         it.runIf(options.transport === 'streamable-http')(
             'should return x402 payment error when calling paymentRequired tool without payment signature',
@@ -2634,7 +2692,7 @@ export function createIntegrationTestsSuite(
             },
         );
 
-        it('should return required structuredContent fields for ActorRun widget (get-actor-run)', async () => {
+        it('should return required structuredContent fields for get-actor-run', async () => {
             client = await createClientFn({ tools: ['actors', 'runs'] });
 
             // First, start an async actor run to get a runId
@@ -2663,7 +2721,7 @@ export function createIntegrationTestsSuite(
                 startedAt: string;
                 dataset?: {
                     datasetId: string;
-                    itemCount: number;
+                    totalItemCount: number;
                 };
             } };
 
@@ -2678,7 +2736,7 @@ export function createIntegrationTestsSuite(
             if (runContent.structuredContent?.status === 'SUCCEEDED') {
                 expect(runContent.structuredContent?.dataset).toBeDefined();
                 expect(runContent.structuredContent?.dataset?.datasetId).toBeDefined();
-                expect(runContent.structuredContent?.dataset?.itemCount).toBeDefined();
+                expect(runContent.structuredContent?.dataset?.totalItemCount).toBeDefined();
             }
         });
 

tests/integration/suite.ts

@@ -66,7 +66,7 @@ describe('getCategoryTools', () => {
         expect(defaultCallActor).not.toBe(appsCallActor);
     });
 
-    it('should return different get-actor-run variants based on mode', () => {
+    it('should share the same get-actor-run tool across modes (mode-independent)', () => {
         const defaultResult = getCategoryTools('default');
         const appsResult = getCategoryTools('apps');
 
@@ -75,8 +75,8 @@ describe('getCategoryTools', () => {
 
         expect(defaultGetRun).toBeDefined();
         expect(appsGetRun).toBeDefined();
-        // Different objects (different implementations)
-        expect(defaultGetRun).not.toBe(appsGetRun);
+        // Same object — data-only, mode-independent. UI rendering lives in get-actor-run-widget.
+        expect(defaultGetRun).toBe(appsGetRun);
     });
 
     it('should share identical tools for mode-independent categories', () => {