refactor: Split widget flag into base + widget response builders (#1077)

jirispilka · claude · web-flow · commit a387a2ddeab7 · 2026-07-16T09:30:51.000+02:00
Part of #1066 (checkbox: split the `widget` boolean param). `buildStartRunResponse` and `buildGetActorRunSuccessResponse` each took a `widget` boolean and branched internally. Every caller passed a literal — widget tools `true`, everything else `false`/omitted — so the "widget only from `*-widget` tools" rule was enforced by a comment, not the type system. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016pXZvhEoE6Lz3DpBSL3n1Y --- _Generated by [Claude Code](https://claude.ai/code/session_016pXZvhEoE6Lz3DpBSL3n1Y)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/src/resources/widgets.ts b/src/resources/widgets.ts
@@ -182,3 +182,14 @@ export async function resolveAvailableWidgets(baseDir: string): Promise<Map<stri
 export function getWidgetConfig(uri: string): WidgetConfig | undefined {
     return WIDGET_REGISTRY[uri];
 }
+
+/**
+ * Actor-run widget `_meta`, with a per-run `openai/widgetDescription` merged in.
+ * Shared by `buildStartRunWidgetResponse` and `buildGetActorRunWidgetResponse`.
+ */
+export function buildActorRunWidgetMeta(descriptionName: string): NonNullable<Resource['_meta']> {
+    return {
+        ...(getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta ?? {}),
+        'openai/widgetDescription': `Actor run progress for ${descriptionName}`,
+    };
+}
diff --git a/src/tools/actors/actor_executor.ts b/src/tools/actors/actor_executor.ts
@@ -3,7 +3,7 @@ import log from '@apify/log';
 import type { ActorExecutionParams, ActorExecutionResult, ActorExecutor } from '../../types.js';
 import { getConsoleLinkContext } from '../../utils/console_link.js';
 import { redactSkyfirePayId } from '../../utils/logging.js';
-import { buildGetActorRunSuccessResponse } from '../runs/get_actor_run.js';
+import { buildGetActorRunResponse } from '../runs/get_actor_run.js';
 import { abortRunOnSignal, CALL_ACTOR_WAIT_SECS_DEFAULT, fetchActorRunData } from './actor_run_response.js';
 
 /**
@@ -86,9 +86,8 @@ export const actorExecutor: ActorExecutor = {
             dataset.itemsSchema = { type: 'object', properties: params.datasetItemsSchema };
         }
 
-        return buildGetActorRunSuccessResponse({
+        return buildGetActorRunResponse({
             ...fetchResult.result,
-            widget: false,
             linkContext: await getConsoleLinkContext(apifyClient.token, apifyClient),
         }) as ActorExecutionResult;
     },
diff --git a/src/tools/actors/actor_run_response.ts b/src/tools/actors/actor_run_response.ts
@@ -4,7 +4,7 @@ import log from '@apify/log';
 
 import type { ApifyClient } from '../../apify_client.js';
 import { DATASET_SIZE_HINT_BYTES, HELPER_TOOLS, NARROW_OUTPUT_HINT } from '../../const.js';
-import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
+import { buildActorRunWidgetMeta } from '../../resources/widgets.js';
 import type { ConsoleLinkContext } from '../../types.js';
 import {
     buildConsoleDatasetUrl,
@@ -702,24 +702,11 @@ async function waitForRunWithProgress(opts: {
 // -----------------------------------------------------------------------------
 
 /**
- * Build a RunResponse from an already-started ActorRun without waiting.
- * Used when waitSecs=0 (default and apps modes) and by widget variants that return immediately.
- * Storage metadata contains IDs only; pollers/widgets fetch updates via get-actor-run.
- *
- * Pass `widget: true` for widget-rendered responses: nextStep is replaced with a no-poll
- * message and widget _meta is included so the UI renders automatically.
- *
- * Invariant: `widget: true` is only valid from `*-widget` tools. Non-widget tools (call-actor,
- * direct actor tools) must omit it or pass `false`.
+ * Shared construction for the immediate start response, used by both the base and widget
+ * builders below. Returns the full `RunResponse` with the computed (non-widget) `nextStep`;
+ * `buildStartRunWidgetResponse` overrides `nextStep` on its own copy.
  */
-export function buildStartRunResponse(params: {
-    actorName: string;
-    actorRun: ActorRun;
-    widget?: boolean;
-    linkContext?: ConsoleLinkContext;
-}): ToolResponse {
-    const { actorName, actorRun, widget, linkContext } = params;
-
+function buildStartRunSharedContent(actorName: string, actorRun: ActorRun): RunResponse {
     // Start path returns before any metadata fetch, so every entry — default and aliases — is id-only.
     const datasetIds = buildStorageAliasIds(actorRun.storageIds?.datasets, actorRun.defaultDatasetId ?? undefined);
     const kvIds = buildStorageAliasIds(
@@ -733,15 +720,13 @@ export function buildStartRunResponse(params: {
         Object.fromEntries(Object.entries(kvIds).map(([alias, id]) => [alias, { id }])),
     );
 
-    const { summary, nextStep: computedNextStep } = buildStatusSummaryNextStep({
+    const { summary, nextStep } = buildStatusSummaryNextStep({
         run: actorRun,
         dataset: datasets?.default,
         keyValueStore: keyValueStores?.default,
     });
 
-    const nextStep = widget ? WIDGET_NO_POLL_NEXT_STEP : computedNextStep;
-
-    const structuredContent: RunResponse = {
+    return {
         runId: actorRun.id,
         actorId: actorRun.actId,
         actorName,
@@ -754,19 +739,50 @@ export function buildStartRunResponse(params: {
         summary,
         nextStep,
     };
+}
+
+/**
+ * Build a RunResponse from an already-started ActorRun without waiting.
+ * Used when waitSecs=0 (default and apps modes).
+ * Storage metadata contains IDs only; pollers fetch updates via get-actor-run.
+ */
+export function buildStartRunResponse(params: {
+    actorName: string;
+    actorRun: ActorRun;
+    linkContext?: ConsoleLinkContext;
+}): ToolResponse {
+    const { actorName, actorRun, linkContext } = params;
+
+    const structuredContent = buildStartRunSharedContent(actorName, actorRun);
     const consoleLinks = applyConsoleLinks(structuredContent, linkContext);
 
-    const widgetMeta = widget
-        ? {
-              ...(getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta ?? {}),
-              'openai/widgetDescription': `Actor run progress for ${actorName}`,
-          }
-        : undefined;
+    return respondOk(
+        [
+            JSON.stringify(structuredContent),
+            `${structuredContent.summary}\n${structuredContent.nextStep}${consoleLinks}`,
+        ],
+        { structuredContent },
+    );
+}
+
+/**
+ * Build a RunResponse from an already-started ActorRun for widget-rendered responses:
+ * nextStep is replaced with a no-poll message and widget _meta is included so the UI renders
+ * automatically. Used only by `*-widget` tools.
+ */
+export function buildStartRunWidgetResponse(params: { actorName: string; actorRun: ActorRun }): ToolResponse {
+    const { actorName, actorRun } = params;
+
+    const base = buildStartRunSharedContent(actorName, actorRun);
+    const structuredContent = { ...base, nextStep: WIDGET_NO_POLL_NEXT_STEP };
 
-    return respondOk([JSON.stringify(structuredContent), `${summary}\n${nextStep}${consoleLinks}`], {
-        structuredContent,
-        meta: widgetMeta,
-    });
+    return respondOk(
+        [JSON.stringify(structuredContent), `${structuredContent.summary}\n${structuredContent.nextStep}`],
+        {
+            structuredContent,
+            meta: buildActorRunWidgetMeta(actorName),
+        },
+    );
 }
 
 // -----------------------------------------------------------------------------
diff --git a/src/tools/actors/call_actor.ts b/src/tools/actors/call_actor.ts
@@ -42,7 +42,7 @@ import {
 import { classifyFailureCategory, extractAjvErrorDetails } from '../../utils/tool_status.js';
 import { extractActorId } from '../../utils/tools.js';
 import { actorNameToToolName, isActorBlockedUnderPaymentProvider } from '../actor_tool_naming.js';
-import { buildGetActorRunSuccessResponse } from '../runs/get_actor_run.js';
+import { buildGetActorRunResponse } from '../runs/get_actor_run.js';
 import { actorRunOutputSchema } from '../structured_output_schemas.js';
 import {
     abortRunOnSignal,
@@ -620,7 +620,7 @@ export async function executeCallActor(toolArgs: InternalToolArgs): Promise<Tool
         if ('error' in fetchResult) return fetchResult.error;
 
         return {
-            ...buildGetActorRunSuccessResponse({ ...fetchResult.result, widget: false, linkContext }),
+            ...buildGetActorRunResponse({ ...fetchResult.result, linkContext }),
             toolTelemetry: { actorId: resolvedActorId },
         };
     } catch (error) {
diff --git a/src/tools/runs/get_actor_run.ts b/src/tools/runs/get_actor_run.ts
@@ -2,7 +2,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 
 import { HELPER_TOOLS } from '../../const.js';
-import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
+import { buildActorRunWidgetMeta } from '../../resources/widgets.js';
 import type { ConsoleLinkContext, HelperTool, InternalToolArgs, ToolEntry, ToolInputSchema } from '../../types.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema, fixZodSchemaRequired } from '../../utils/ajv.js';
@@ -86,25 +86,30 @@ export function buildGetActorRunError(runId: string, error: unknown): ToolRespon
 
 /**
  * Build the success response. `content[0]` is the JSON-stringified `structuredContent`
- * mirror (per MCP spec); `content[1]` carries an LLM-readable narrative — `summary` +
- * `nextStep` in default mode, a short pointer in widget mode.
+ * mirror (per MCP spec); `content[1]` carries an LLM-readable narrative of `summary` + `nextStep`.
  */
-export function buildGetActorRunSuccessResponse(
-    params: FetchActorRunResult & { widget: boolean; linkContext?: ConsoleLinkContext },
+export function buildGetActorRunResponse(
+    params: FetchActorRunResult & { linkContext?: ConsoleLinkContext },
 ): ToolResponse {
-    const { run, structuredContent, widget, linkContext } = params;
-
-    if (!widget) {
-        // Mints the `apifyConsoleUrl` fields onto structuredContent and returns the narrative suffix in one pass.
-        const consoleLinks = applyConsoleLinks(structuredContent, linkContext);
-        return respondOk(
-            [
-                JSON.stringify(structuredContent),
-                `${structuredContent.summary}\n${structuredContent.nextStep}${consoleLinks}`,
-            ],
-            { structuredContent, meta: buildUsageMeta(run) },
-        );
-    }
+    const { run, structuredContent, linkContext } = params;
+
+    // Mints the `apifyConsoleUrl` fields onto structuredContent and returns the narrative suffix in one pass.
+    const consoleLinks = applyConsoleLinks(structuredContent, linkContext);
+    return respondOk(
+        [
+            JSON.stringify(structuredContent),
+            `${structuredContent.summary}\n${structuredContent.nextStep}${consoleLinks}`,
+        ],
+        { structuredContent, meta: buildUsageMeta(run) },
+    );
+}
+
+/**
+ * Build the widget success response. `content[1]` carries a short pointer instead of the
+ * summary/nextStep narrative. Used only by `*-widget` tools; does not apply console links.
+ */
+export function buildGetActorRunWidgetResponse(params: FetchActorRunResult): ToolResponse {
+    const { run, structuredContent } = params;
 
     // Override nextStep so the model reading structuredContent (content[0]) also sees no-poll guidance.
     const widgetContent = { ...structuredContent, nextStep: WIDGET_NO_POLL_NEXT_STEP };
@@ -116,9 +121,8 @@ export function buildGetActorRunSuccessResponse(
         {
             structuredContent: widgetContent,
             meta: {
-                ...(getWidgetConfig(WIDGET_URIS.ACTOR_RUN)?.meta ?? {}),
+                ...buildActorRunWidgetMeta(structuredContent.actorName ?? structuredContent.runId),
                 ...(buildUsageMeta(run) ?? {}),
-                'openai/widgetDescription': `Actor run progress for ${structuredContent.actorName ?? structuredContent.runId}`,
             },
         },
     );
@@ -148,9 +152,8 @@ export const getActorRun: ToolEntry = Object.freeze({
             if ('aborted' in fetchResult) return respondAborted();
             if ('error' in fetchResult) return fetchResult.error;
 
-            return buildGetActorRunSuccessResponse({
+            return buildGetActorRunResponse({
                 ...fetchResult.result,
-                widget: false,
                 linkContext: await getConsoleLinkContext(apifyToken, client),
             });
         } catch (error) {
diff --git a/src/tools/widgets/call_actor_widget.ts b/src/tools/widgets/call_actor_widget.ts
@@ -10,7 +10,7 @@ import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
 import { respondServerError } from '../../utils/mcp.js';
 import { extractActorId } from '../../utils/tools.js';
-import { buildStartRunResponse } from '../actors/actor_run_response.js';
+import { buildStartRunWidgetResponse } from '../actors/actor_run_response.js';
 import {
     buildCallActorErrorResponse,
     callActorPreExecute,
@@ -120,7 +120,7 @@ export const callActorWidget: ToolEntry = Object.freeze({
                 runId: actorRun.id,
                 mcpSessionId: toolArgs.mcpSessionId,
             });
-            const response = buildStartRunResponse({ actorName: baseActorName, actorRun, widget: true });
+            const response = buildStartRunWidgetResponse({ actorName: baseActorName, actorRun });
             return {
                 ...response,
                 toolTelemetry: { actorId: resolvedActorId },
diff --git a/src/tools/widgets/get_actor_run_widget.ts b/src/tools/widgets/get_actor_run_widget.ts
@@ -9,7 +9,7 @@ import { compileSchema } from '../../utils/ajv.js';
 import { logHttpError } from '../../utils/logging.js';
 import { respondAborted } from '../../utils/mcp.js';
 import { fetchActorRunData } from '../actors/actor_run_response.js';
-import { buildGetActorRunError, buildGetActorRunSuccessResponse } from '../runs/get_actor_run.js';
+import { buildGetActorRunError, buildGetActorRunWidgetResponse } from '../runs/get_actor_run.js';
 import { actorRunOutputSchema } from '../structured_output_schemas.js';
 
 /**
@@ -72,7 +72,7 @@ export const getActorRunWidget: ToolEntry = Object.freeze({
             if ('aborted' in fetchResult) return respondAborted();
             if ('error' in fetchResult) return fetchResult.error;
 
-            return buildGetActorRunSuccessResponse({ ...fetchResult.result, widget: true });
+            return buildGetActorRunWidgetResponse({ ...fetchResult.result });
         } catch (error) {
             logHttpError(error, 'Failed to get Actor run (widget)', { runId: parsed.runId });
             return buildGetActorRunError(parsed.runId, error);
diff --git a/tests/unit/tools.get_actor_run.response.test.ts b/tests/unit/tools.get_actor_run.response.test.ts
@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import {
     buildStartRunResponse,
+    buildStartRunWidgetResponse,
     buildStatusSummaryNextStep,
     collapseArrayIndices,
     type RunDataset,
@@ -647,16 +648,18 @@ describe('get-actor-run default response', () => {
 // buildStartRunResponse — the "fire and forget" (waitSecs=0) response builder
 // -----------------------------------------------------------------------------
 
-describe('buildStartRunResponse()', () => {
-    const actorRun = {
-        id: 'run-abc',
-        actId: 'actor-xyz',
-        status: 'RUNNING',
-        startedAt: new Date('2026-01-02T03:04:05.000Z'),
-        defaultDatasetId: 'dataset-abc',
-        defaultKeyValueStoreId: 'kv-abc',
-    } as unknown as ActorRun;
+// Shared by buildStartRunResponse() and buildStartRunWidgetResponse() below — both builders
+// consume the same ActorRun shape.
+const actorRun = {
+    id: 'run-abc',
+    actId: 'actor-xyz',
+    status: 'RUNNING',
+    startedAt: new Date('2026-01-02T03:04:05.000Z'),
+    defaultDatasetId: 'dataset-abc',
+    defaultKeyValueStoreId: 'kv-abc',
+} as unknown as ActorRun;
 
+describe('buildStartRunResponse()', () => {
     it('builds correct RunResponse shape without widget metadata', () => {
         const result = buildStartRunResponse({ actorName: 'apify/rag-web-browser', actorRun });
 
@@ -730,12 +733,13 @@ describe('buildStartRunResponse()', () => {
         expect(content[1].text).toContain('Apify Console: run https://console.apify.com/actors/runs/run-abc');
         expect(content[1].text).toContain(VERBATIM_LINKS_NUDGE);
     });
+});
 
-    it('includes widget metadata and no-poll nextStep when widget=true', () => {
-        const result = buildStartRunResponse({
+describe('buildStartRunWidgetResponse()', () => {
+    it('includes widget metadata and a no-poll nextStep', () => {
+        const result = buildStartRunWidgetResponse({
             actorName: 'apify/rag-web-browser',
             actorRun,
-            widget: true,
         });
 
         const { structuredContent, _meta } = result as {
diff --git a/tests/unit/tools.get_actor_run.widget.response.test.ts b/tests/unit/tools.get_actor_run.widget.response.test.ts
@@ -18,6 +18,8 @@ const MOCK_RUN_RUNNING = {
     status: 'RUNNING',
     startedAt: new Date('2026-04-20T12:00:00.000Z'),
     stats: { runTimeSecs: 5, computeUnits: 0.01, memMaxBytes: 1024 },
+    usageTotalUsd: 0.0002,
+    usageUsd: { ACTOR_COMPUTE_UNITS: 0.0002 },
 };
 
 const MOCK_ACTOR = {
@@ -48,6 +50,7 @@ describe('get-actor-run-widget response', () => {
             _meta?: {
                 ui?: { resourceUri?: string; visibility?: readonly string[]; csp?: unknown };
                 'openai/widgetDescription'?: string;
+                'com.apify/ActorRun'?: { usageTotalUsd?: number; usageUsd?: unknown };
             };
         };
 
@@ -71,6 +74,11 @@ describe('get-actor-run-widget response', () => {
         expect(_meta?.ui?.visibility).toEqual(['model', 'app']);
         expect(_meta?.ui?.csp).toBeDefined();
         expect(_meta?.['openai/widgetDescription']).toContain('apify/rag-web-browser');
+        // Widget _meta also carries run usage metadata (buildUsageMeta), alongside widget-specific meta.
+        expect(_meta?.['com.apify/ActorRun']).toEqual({
+            usageTotalUsd: 0.0002,
+            usageUsd: { ACTOR_COMPUTE_UNITS: 0.0002 },
+        });
     });
 
     it('carries widget _meta on the tool definition', () => {
