refactor: Simplify fetch-actor-details — deduplicate handler, colocate schemas, clean utils (#694)

* refactor: Deduplicate fetch-actor-details handler logic

Extract shared handler body from default and internal variants into
buildFetchActorDetailsResult in fetch_actor_details_common.ts. Apply
dedent to multiline strings. Remove duplicated args schema from
internal tool.

https://claude.ai/code/session_01BdYJoEQKitqiF1i8g1XAxv

* chore: Update package-lock.json

https://claude.ai/code/session_01BdYJoEQKitqiF1i8g1XAxv

* refactor: Narrow route param type to HelperTools enum

Use HelperTools.ACTOR_GET_DETAILS / ACTOR_GET_DETAILS_INTERNAL instead
of loosely-typed string for the route parameter of
buildFetchActorDetailsResult.

* refactor: Simplify buildActorDetailsTextResponse signature

Reduce from 9 params to 4 by making it pure/sync. The caller now
pre-resolves mcpToolsMessage when output.mcpTools is true, so the
apifyClient/apifyToken/paymentProvider/mcpSessionId/actorName
parameters are no longer needed inside the formatter. Drop redundant
cardOptions param (derivable from output). Extract ResolvedOutputOptions
type from actorDetailsOutputDefaults.

* refactor: Colocate fetch-actor-details schemas and response builders

Move tool-specific items from src/utils/actor_details.ts to
src/tools/core/fetch_actor_details_common.ts — matching the structure
of src/tools/core/search_actors_common.ts:

  - actorDetailsOutputOptionsSchema
  - actorDetailsOutputDefaults
  - ResolvedOutputOptions
  - resolveOutputOptions
  - buildActorNotFoundResponse
  - buildActorDetailsTextResponse

utils/actor_details.ts now holds only shared data-fetching and
formatting utilities (fetchActorDetails, getMcpToolsMessage,
processActorDetailsForResponse, resolveReadmeContent,
buildCardOptions, typeObjectToString, ActorDetailsResult).

Export typeObjectToString since buildActorDetailsTextResponse (now
in tools/core) still uses it.

* refactor: Apply dedent / texts[] array convention to long strings

Per CONTRIBUTING.md, replace long single-line templates with \n
escapes using the appropriate pattern for each case:

- dedent for multi-line strings with safe interpolations
  (buildActorNotFoundResponse, Output Schema TypeScript block,
  No output schema fallback)
- texts[] array joined with \n for strings that embed JSON.stringify
  or multi-line interpolations (input schema block, per-tool MCP
  formatting in getMcpToolsMessage, and its final wrapper with
  mcpToolsInfo)

* refactor: Simplify actor_details utils

- typeObjectToString / typeValueToString: collapse 35 lines of
  mutual recursion into 13; preserve top-level skip behavior via
  Object.entries().filter(). Behavior equivalence verified by 17
  new unit tests.
- fetchActorDetails: cache apifyClient.actor(actorName) (was called
  twice), hoist actorSlug, reformat Promise.all cleanly (the
  third entry had been mangled by a prior lint auto-fix).
- processActorDetailsForResponse → rename to buildActorDetailsForWidget
  (better describes what it does). Drop dead code: the returned
  `texts` array and top-level `formattedReadme` were never consumed.
  Flatten structuredContent wrapper: caller immediately peeled it.

* refactor: Clarify test description for nested array type handling

* fix: Review comments

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jirispilka

package-lock.json

@@ -1,13 +1,80 @@
+import dedent from 'dedent';
 import { z } from 'zod';
 
-import { HelperTools } from '../../const.js';
+import { ApifyClient } from '../../apify_client.js';
+import { FAILURE_CATEGORY, HelperTools, TOOL_STATUS } from '../../const.js';
 import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
-import type { HelperTool, ToolInputSchema } from '../../types.js';
+import type { HelperTool, InternalToolArgs, ToolInputSchema } from '../../types.js';
 import {
-    actorDetailsOutputOptionsSchema,
+    type ActorDetailsResult,
+    buildCardOptions,
+    fetchActorDetails,
+    getMcpToolsMessage,
+    resolveReadmeContent,
+    typeObjectToString,
 } from '../../utils/actor_details.js';
 import { compileSchema } from '../../utils/ajv.js';
+import { buildMCPResponse } from '../../utils/mcp.js';
 import { actorDetailsOutputSchema } from '../structured_output_schemas.js';
+import { fixActorNameInputAndLog } from './actor_tools_factory.js';
+
+/**
+ * Shared schema for actor details output options.
+ *
+ * Behavior:
+ * - If output is undefined or empty object: use defaults (all true except mcpTools and outputSchema)
+ * - If any property is explicitly set: only include sections with explicit true values
+ */
+export const actorDetailsOutputOptionsSchema = z.object({
+    description: z.boolean().optional().describe('Include Actor description text only.'),
+    stats: z.boolean().optional().describe('Include usage statistics (users, runs, success rate).'),
+    pricing: z.boolean().optional().describe('Include pricing model and costs.'),
+    rating: z.boolean().optional().describe('Include user rating (out of 5 stars).'),
+    metadata: z.boolean().optional().describe('Include developer, categories, last modified date, and deprecation status.'),
+    inputSchema: z.boolean().optional().describe('Include required input parameters schema.'),
+    readme: z.boolean().optional().describe('Include Actor README documentation (summary when available, full otherwise).'),
+    outputSchema: z.boolean().optional().describe('Include inferred output schema from recent successful runs (TypeScript type).'),
+    mcpTools: z.boolean().optional().describe('List available tools (only for MCP server Actors).'),
+});
+
+export const actorDetailsOutputDefaults = {
+    description: true,
+    stats: true,
+    pricing: true,
+    rating: true,
+    metadata: true,
+    inputSchema: true,
+    readme: true,
+    outputSchema: false,
+    mcpTools: false,
+};
+
+export type ResolvedOutputOptions = typeof actorDetailsOutputDefaults;
+
+/**
+ * Resolve output options with smart defaults.
+ * If output is undefined/empty, returns defaults.
+ * If any property is explicitly set, undefined properties are treated as false.
+ */
+export function resolveOutputOptions(output?: z.infer<typeof actorDetailsOutputOptionsSchema>): ResolvedOutputOptions {
+    const hasExplicitOptions = output && Object.values(output).some((v) => v !== undefined);
+
+    if (!hasExplicitOptions) {
+        return actorDetailsOutputDefaults;
+    }
+
+    return {
+        description: output?.description === true,
+        stats: output?.stats === true,
+        pricing: output?.pricing === true,
+        rating: output?.rating === true,
+        metadata: output?.metadata === true,
+        inputSchema: output?.inputSchema === true,
+        readme: output?.readme === true,
+        outputSchema: output?.outputSchema === true,
+        mcpTools: output?.mcpTools === true,
+    };
+}
 
 /**
  * Zod schema for fetch-actor-details arguments — shared between default and openai variants.
@@ -58,3 +125,134 @@ export const fetchActorDetailsMetadata: Omit<HelperTool, 'call'> = {
         openWorldHint: false,
     },
 };
+
+/**
+ * Build error response for when actor is not found.
+ */
+export function buildActorNotFoundResponse(actorName: string): ReturnType<typeof buildMCPResponse> {
+    return buildMCPResponse({
+        texts: [dedent`
+            Actor information for '${actorName}' was not found.
+            Please verify Actor ID or name format and ensure that the Actor exists.
+            You can search for available Actors using the tool: ${HelperTools.STORE_SEARCH}.
+        `],
+        isError: true,
+        telemetry: { toolStatus: TOOL_STATUS.SOFT_FAIL, failureCategory: FAILURE_CATEGORY.INVALID_INPUT },
+    });
+}
+
+/**
+ * Build text and structured response for actor details.
+ * Pure/sync: the caller pre-resolves `mcpToolsMessage` when `output.mcpTools` is true.
+ */
+export function buildActorDetailsTextResponse(options: {
+    details: ActorDetailsResult;
+    output: ResolvedOutputOptions;
+    actorOutputSchema?: Record<string, unknown> | null;
+    mcpToolsMessage?: string;
+}): {
+    texts: string[];
+    structuredContent: Record<string, unknown>;
+} {
+    const { details, output, actorOutputSchema, mcpToolsMessage } = options;
+
+    const actorUrl = `https://apify.com/${details.actorInfo.username}/${details.actorInfo.name}`;
+
+    const texts: string[] = [];
+
+    const needsCard = output.description
+        || output.stats
+        || output.pricing
+        || output.rating
+        || output.metadata;
+
+    if (needsCard) {
+        texts.push(`# Actor information\n${details.actorCard}`);
+    }
+
+    const resolvedReadme = output.readme ? resolveReadmeContent(details) : undefined;
+    if (resolvedReadme) {
+        texts.push(`${resolvedReadme.heading}\n${resolvedReadme.content}`);
+    }
+
+    if (output.inputSchema) {
+        texts.push([
+            `# [Input schema](${actorUrl}/input)`,
+            '```json',
+            JSON.stringify(details.inputSchema),
+            '```',
+        ].join('\n'));
+    }
+
+    if (output.outputSchema) {
+        if (actorOutputSchema && Object.keys(actorOutputSchema).length > 0) {
+            const typeString = typeObjectToString(actorOutputSchema);
+            texts.push(dedent`
+                # Output Schema (TypeScript)
+                Inferred from recent successful runs:
+                \`\`\`typescript
+                type ActorOutput = ${typeString}
+                \`\`\`
+            `);
+        } else {
+            texts.push(dedent`
+                # Output Schema
+                No output schema available. The Actor may not have recent successful runs, or the output structure could not be determined.
+            `);
+        }
+    }
+
+    if (mcpToolsMessage) {
+        texts.push(mcpToolsMessage);
+    }
+
+    const structuredContent: Record<string, unknown> = {
+        actorInfo: needsCard ? details.actorCardStructured : undefined,
+        readme: resolvedReadme?.content,
+        inputSchema: output.inputSchema ? details.inputSchema : undefined,
+        outputSchema: output.outputSchema ? (actorOutputSchema ?? {}) : undefined,
+    };
+
+    return { texts, structuredContent };
+}
+
+/**
+ * Shared handler for default and internal fetch-actor-details variants.
+ * Both return the same text + structured response; only the telemetry route differs.
+ */
+export async function buildFetchActorDetailsResult(
+    toolArgs: InternalToolArgs,
+    route: HelperTools.ACTOR_GET_DETAILS | HelperTools.ACTOR_GET_DETAILS_INTERNAL,
+): Promise<ReturnType<typeof buildMCPResponse>> {
+    const { args, apifyToken, apifyMcpServer, mcpSessionId } = toolArgs;
+    const parsed = fetchActorDetailsToolArgsSchema.parse(args);
+    const actorName = fixActorNameInputAndLog(parsed.actor, { mcpSessionId, route });
+    const apifyClient = new ApifyClient({ token: apifyToken });
+
+    const resolvedOutput = resolveOutputOptions(parsed.output);
+    const details = await fetchActorDetails(apifyClient, actorName, buildCardOptions(resolvedOutput));
+    if (!details) {
+        return buildActorNotFoundResponse(actorName);
+    }
+
+    let actorOutputSchema: Record<string, unknown> | null | undefined;
+    if (resolvedOutput.outputSchema) {
+        actorOutputSchema = apifyMcpServer.actorStore
+            ? await apifyMcpServer.actorStore.getActorOutputSchemaAsTypeObject(actorName).catch(() => null)
+            : null;
+    }
+    const mcpToolsMessage = resolvedOutput.mcpTools
+        ? await getMcpToolsMessage(actorName, apifyClient, apifyToken, apifyMcpServer?.options.paymentProvider, mcpSessionId)
+        : undefined;
+
+    // NOTE: Data duplication between texts and structuredContent is intentional and required.
+    // Some MCP clients only read text content, while others only read structured content.
+    const { texts, structuredContent } = buildActorDetailsTextResponse({
+        details,
+        output: resolvedOutput,
+        actorOutputSchema,
+        mcpToolsMessage,
+    });
+
+    return buildMCPResponse({ texts, structuredContent });
+}

src/tools/core/fetch_actor_details_common.ts

@@ -1,17 +1,8 @@
-import { ApifyClient } from '../../apify_client.js';
-import type { InternalToolArgs, ToolEntry } from '../../types.js';
-import {
-    buildActorDetailsTextResponse,
-    buildActorNotFoundResponse,
-    buildCardOptions,
-    fetchActorDetails,
-    resolveOutputOptions,
-} from '../../utils/actor_details.js';
-import { buildMCPResponse } from '../../utils/mcp.js';
-import { fixActorNameInputAndLog } from '../core/actor_tools_factory.js';
+import { HelperTools } from '../../const.js';
+import type { ToolEntry } from '../../types.js';
 import {
+    buildFetchActorDetailsResult,
     fetchActorDetailsMetadata,
-    fetchActorDetailsToolArgsSchema,
 } from '../core/fetch_actor_details_common.js';
 
 /**
@@ -20,39 +11,5 @@ import {
  */
 export const defaultFetchActorDetails: ToolEntry = Object.freeze({
     ...fetchActorDetailsMetadata,
-    call: async (toolArgs: InternalToolArgs) => {
-        const { args, apifyToken, apifyMcpServer, mcpSessionId } = toolArgs;
-        const parsedArgs = fetchActorDetailsToolArgsSchema.parse(args);
-        const actorName = fixActorNameInputAndLog(parsedArgs.actor, { mcpSessionId, route: 'fetch-actor-details' });
-        const apifyClient = new ApifyClient({ token: apifyToken });
-
-        const resolvedOutput = resolveOutputOptions(parsedArgs.output);
-        const cardOptions = buildCardOptions(resolvedOutput);
-
-        const details = await fetchActorDetails(apifyClient, actorName, cardOptions);
-        if (!details) {
-            return buildActorNotFoundResponse(actorName);
-        }
-
-        // Fetch output schema from ActorStore if available and requested
-        const actorOutputSchema = resolvedOutput.outputSchema
-            ? await apifyMcpServer.actorStore?.getActorOutputSchemaAsTypeObject(actorName).catch(() => null)
-            : undefined;
-
-        // NOTE: Data duplication between texts and structuredContent is intentional and required.
-        // Some MCP clients only read text content, while others only read structured content.
-        const { texts, structuredContent: responseStructuredContent } = await buildActorDetailsTextResponse({
-            actorName,
-            details,
-            output: resolvedOutput,
-            cardOptions,
-            apifyClient,
-            apifyToken,
-            actorOutputSchema,
-            paymentProvider: apifyMcpServer?.options.paymentProvider,
-            mcpSessionId,
-        });
-
-        return buildMCPResponse({ texts, structuredContent: responseStructuredContent });
-    },
+    call: async (toolArgs) => buildFetchActorDetailsResult(toolArgs, HelperTools.ACTOR_GET_DETAILS),
 } as const);

src/tools/default/fetch_actor_details.ts

@@ -1,18 +1,20 @@
+import dedent from 'dedent';
+
 import { ApifyClient } from '../../apify_client.js';
 import { getWidgetConfig, WIDGET_URIS } from '../../resources/widgets.js';
 import type { InternalToolArgs, ToolEntry } from '../../types.js';
 import {
-    buildActorNotFoundResponse,
+    buildActorDetailsForWidget,
     buildCardOptions,
     fetchActorDetails,
-    processActorDetailsForResponse,
-    resolveOutputOptions,
 } from '../../utils/actor_details.js';
 import { buildMCPResponse } from '../../utils/mcp.js';
 import { fixActorNameInputAndLog } from '../core/actor_tools_factory.js';
 import {
+    buildActorNotFoundResponse,
     fetchActorDetailsMetadata,
     fetchActorDetailsToolArgsSchema,
+    resolveOutputOptions,
 } from '../core/fetch_actor_details_common.js';
 
 /**
@@ -27,28 +29,26 @@ export const openaiFetchActorDetails: ToolEntry = Object.freeze({
         const actorName = fixActorNameInputAndLog(parsed.actor, { mcpSessionId, route: 'fetch-actor-details' });
         const apifyClient = new ApifyClient({ token: apifyToken });
 
-        const resolvedOutput = resolveOutputOptions(parsed.output);
-        const cardOptions = buildCardOptions(resolvedOutput);
-
+        const cardOptions = buildCardOptions(resolveOutputOptions(parsed.output));
         const details = await fetchActorDetails(apifyClient, actorName, cardOptions);
         if (!details) {
             return buildActorNotFoundResponse(actorName);
         }
 
-        const { structuredContent: processedStructuredContent, actorUrl } = processActorDetailsForResponse(details);
+        const { actorUrl, actorDetails } = buildActorDetailsForWidget(details);
         const structuredContent = {
             actorInfo: details.actorCardStructured,
             inputSchema: details.inputSchema,
-            actorDetails: processedStructuredContent.actorDetails,
+            actorDetails,
         };
 
-        const texts = [`
-# Actor information:
-- **Actor:** ${actorName}
-- **URL:** ${actorUrl}
+        const texts = [dedent`
+            # Actor information:
+            - **Actor:** ${actorName}
+            - **URL:** ${actorUrl}
 
-An interactive widget has been rendered with detailed Actor information.
-`];
+            An interactive widget has been rendered with detailed Actor information.
+        `];
 
         const widgetConfig = getWidgetConfig(WIDGET_URIS.SEARCH_ACTORS);
         return buildMCPResponse({