refactor: switch tools-loader to buildCategories(uiMode), remove deep-clone hack

Refactor loadToolsFromInput() to use buildCategories(uiMode) instead of the
static toolCategories map. This eliminates three legacy workarounds:

1. Deep-clone hack (JSON.parse/stringify with function stripping/reattachment)
   — no longer needed since buildCategories() returns the correct variant directly
   and tool definitions are frozen (Object.freeze from PR #4)

2. openaiOnly runtime filter — no longer needed since buildCategories() returns
   ui: [] in default mode (openai-only tools are never included)

3. call-actor description mutation — no longer needed since each mode variant
   has its own description baked in

Also:
- Add two-level internal tool name classification: mode-specific map for selection,
  all-names set for preventing misclassification as Actor IDs
- Remove openaiOnly from internal tool definitions (no longer used for filtering)
- Deprecate openaiOnly in ToolBase type (kept for cross-repo compat)
- Remove dead getCallActorDescription() function
- Deprecate callActor adapter in actor.ts

Author: MQ37

src/tools/actor.ts

@@ -9,24 +9,14 @@
  * This adapter file maintains backward compatibility for existing imports.
  * PR #4 will wire variants directly into the category registry, making this adapter unnecessary.
  */
-import type { HelperTool, InternalToolArgs, ToolEntry, UiMode } from '../types.js';
+import type { HelperTool, InternalToolArgs, ToolEntry } from '../types.js';
 import { defaultCallActor } from './default/call-actor.js';
 import { openaiCallActor } from './openai/call-actor.js';
 
 // Re-exports to maintain backward compatibility and support other modules
 export { callActorGetDataset, type CallActorGetDatasetResult } from './core/actor-execution.js';
 export { getActorsAsTools } from './core/actor-tools-factory.js';
 
-/**
- * Returns the call-actor description for the given UI mode.
- * Maintained for backward compatibility with tools-loader.ts which mutates the description at load time.
- * PR #4 will remove this in favor of direct variant registration.
- */
-export function getCallActorDescription(uiMode?: UiMode): string {
-    const variant = uiMode === 'openai' ? openaiCallActor : defaultCallActor;
-    return variant.description ?? '';
-}
-
 const defaultVariant = defaultCallActor as HelperTool;
 
 /**
@@ -35,7 +25,8 @@ const defaultVariant = defaultCallActor as HelperTool;
  * The tool definition (name, inputSchema, outputSchema, etc.) uses the default variant's metadata.
  * The `call` handler inspects `apifyMcpServer.options.uiMode` to delegate to the right implementation.
  *
- * Note: The description may be overridden by tools-loader.ts at load time for openai mode.
+ * @deprecated This adapter is no longer needed — buildCategories(uiMode) returns the correct
+ * variant directly. Will be removed once all consumers are migrated.
  */
 export const callActor: ToolEntry = Object.freeze({
     ...defaultVariant,

src/tools/openai/fetch-actor-details-internal.ts

@@ -26,7 +26,6 @@ const fetchActorDetailsInternalArgsSchema = z.object({
 export const fetchActorDetailsInternalTool: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.ACTOR_GET_DETAILS_INTERNAL,
-    openaiOnly: true,
     description: `Fetch Actor details with flexible output options (UI mode internal tool).
 
 This tool is available because the LLM is operating in UI mode. Use it for internal lookups

src/tools/openai/search-actors-internal.ts

@@ -30,7 +30,6 @@ const searchActorsInternalArgsSchema = z.object({
 export const searchActorsInternalTool: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.STORE_SEARCH_INTERNAL,
-    openaiOnly: true,
     description: `Search Actors internally (UI mode internal tool).
 
 This tool is available because the LLM is operating in UI mode. Use it for internal lookups 

src/types.ts

@@ -91,7 +91,11 @@ export type ToolBase = z.infer<typeof ToolSchema> & {
     ajvValidate: ValidateFunction;
     /** Whether this tool requires Skyfire pay ID validation (uses Apify API) */
     requiresSkyfirePayId?: boolean;
-    /** Whether this tool is only available in OpenAI UI mode */
+    /**
+     * Whether this tool is only available in OpenAI UI mode.
+     * @deprecated No longer used for filtering. Mode-specific tools are resolved at build time
+     * via buildCategories(uiMode). Will be removed in a future release.
+     */
     openaiOnly?: boolean;
 };
 

src/utils/tools-loader.ts

@@ -3,30 +3,38 @@
  * This eliminates duplication between stdio.ts and processParamsGetTools.
  */
 
-import type { ValidateFunction } from 'ajv';
 import type { ApifyClient } from 'apify';
 
 import log from '@apify/log';
 
 import { defaults, HelperTools } from '../const.js';
-import { callActor, getCallActorDescription } from '../tools/actor.js';
+import { buildCategories, CATEGORY_NAMES, toolCategoriesEnabledByDefault } from '../tools/categories.js';
 import { getActorOutput } from '../tools/common/get-actor-output.js';
 import { addTool } from '../tools/common/helpers.js';
-import { getActorRun } from '../tools/common/run.js';
-import { getActorsAsTools, toolCategories, toolCategoriesEnabledByDefault } from '../tools/index.js';
-import type { ActorStore, Input, InternalToolArgs, ToolCategory, ToolEntry, UiMode } from '../types.js';
-import { getExpectedToolsByCategories } from './tool-categories-helpers.js';
-
-// Lazily-computed cache of internal tools by name to avoid circular init issues.
-let INTERNAL_TOOL_BY_NAME_CACHE: Map<string, ToolEntry> | null = null;
-function getInternalToolByNameMap(): Map<string, ToolEntry> {
-    if (!INTERNAL_TOOL_BY_NAME_CACHE) {
-        const allInternal = getExpectedToolsByCategories(Object.keys(toolCategories) as ToolCategory[]);
-        INTERNAL_TOOL_BY_NAME_CACHE = new Map<string, ToolEntry>(
-            allInternal.map((entry) => [entry.name, entry]),
-        );
+import { getActorsAsTools } from '../tools/index.js';
+import type { ActorStore, Input, ToolCategory, ToolEntry, UiMode } from '../types.js';
+
+/**
+ * Set of all known internal tool names across ALL modes.
+ * Used for classifying selectors: if a selector matches a known internal tool name,
+ * it's not treated as an Actor ID — even if it's absent from the current mode's categories.
+ */
+let ALL_INTERNAL_TOOL_NAMES_CACHE: Set<string> | null = null;
+function getAllInternalToolNames(): Set<string> {
+    if (!ALL_INTERNAL_TOOL_NAMES_CACHE) {
+        const allNames = new Set<string>();
+        // Collect tool names from both modes to ensure complete classification
+        for (const mode of [undefined, 'openai' as UiMode]) {
+            const categories = buildCategories(mode);
+            for (const name of CATEGORY_NAMES) {
+                for (const tool of categories[name]) {
+                    allNames.add(tool.name);
+                }
+            }
+        }
+        ALL_INTERNAL_TOOL_NAMES_CACHE = allNames;
     }
-    return INTERNAL_TOOL_BY_NAME_CACHE;
+    return ALL_INTERNAL_TOOL_NAMES_CACHE;
 }
 
 /**
@@ -44,6 +52,9 @@ export async function loadToolsFromInput(
     uiMode?: UiMode,
     actorStore?: ActorStore,
 ): Promise<ToolEntry[]> {
+    // Build mode-resolved categories — tools are already the correct variant for this mode
+    const categories = buildCategories(uiMode);
+
     // Helpers for readability
     const normalizeSelectors = (value: Input['tools']): (string | ToolCategory)[] | undefined => {
         if (value === undefined) return undefined;
@@ -59,6 +70,14 @@ export async function loadToolsFromInput(
     const addActorEnabled = input.enableAddingActors === true;
     const actorsExplicitlyEmpty = (Array.isArray(input.actors) && input.actors.length === 0) || input.actors === '';
 
+    // Build mode-specific tool-by-name map for individual tool selection
+    const modeToolByName = new Map<string, ToolEntry>();
+    for (const name of CATEGORY_NAMES) {
+        for (const tool of categories[name]) {
+            modeToolByName.set(tool.name, tool);
+        }
+    }
+
     // Partition selectors into internal picks (by category or by name) and Actor names
     const internalSelections: ToolEntry[] = [];
     const actorSelectorsFromTools: string[] = [];
@@ -67,21 +86,27 @@ export async function loadToolsFromInput(
             if (selector === 'preview') {
                 // 'preview' category is deprecated. It contained `call-actor` which is now default
                 log.warning('Tool category "preview" is deprecated');
-                internalSelections.push(callActor);
+                const callActorTool = modeToolByName.get(HelperTools.ACTOR_CALL);
+                if (callActorTool) internalSelections.push(callActorTool);
                 continue;
             }
 
-            const categoryTools = toolCategories[selector as ToolCategory];
+            const categoryTools = categories[selector as ToolCategory];
 
             if (categoryTools) {
                 internalSelections.push(...categoryTools);
                 continue;
             }
-            const internalByName = getInternalToolByNameMap().get(String(selector));
+            const internalByName = modeToolByName.get(String(selector));
             if (internalByName) {
                 internalSelections.push(internalByName);
                 continue;
             }
+            // If this is a known internal tool name (from another mode), skip it silently
+            // rather than treating it as an Actor ID
+            if (getAllInternalToolNames().has(String(selector))) {
+                continue;
+            }
             // Treat unknown selectors as Actor IDs/full names.
             // Potential heuristic (future): if (String(selector).includes('/')) => definitely an Actor.
             actorSelectorsFromTools.push(String(selector));
@@ -123,12 +148,15 @@ export async function loadToolsFromInput(
         // No selectors: either expose only add-actor (when enabled), or default categories
         result.push(addTool);
     } else if (!actorsExplicitlyEmpty) {
-        result.push(...getExpectedToolsByCategories(toolCategoriesEnabledByDefault));
+        // Use mode-resolved default categories
+        for (const cat of toolCategoriesEnabledByDefault) {
+            result.push(...categories[cat]);
+        }
     }
 
-    // In openai mode, add UI-specific tools
+    // In openai mode, unconditionally add UI-specific tools (regardless of selectors)
     if (uiMode === 'openai') {
-        result.push(...(toolCategories.ui || []));
+        result.push(...categories.ui);
     }
 
     // Actor tools (if any)
@@ -141,6 +169,8 @@ export async function loadToolsFromInput(
      * Auto-inject get-actor-run and get-actor-output when call-actor or actor tools are present.
      * Insert them right after call-actor to follow the logical workflow order:
      * search → details → call → run status → output → docs → actor tools
+     *
+     * Uses mode-resolved variants from buildCategories() for get-actor-run.
      */
     const hasCallActor = result.some((entry) => entry.name === HelperTools.ACTOR_CALL);
     const hasActorTools = result.some((entry) => entry.type === 'actor');
@@ -150,7 +180,9 @@ export async function loadToolsFromInput(
 
     const toolsToInject: ToolEntry[] = [];
     if (!hasGetActorRun && (hasCallActor || uiMode === 'openai')) {
-        toolsToInject.push(getActorRun);
+        // Use mode-resolved get-actor-run variant
+        const modeGetActorRun = modeToolByName.get(HelperTools.ACTOR_RUNS_GET);
+        if (modeGetActorRun) toolsToInject.push(modeGetActorRun);
     }
     if (!hasGetActorOutput && (hasCallActor || hasActorTools || hasAddActorTool)) {
         toolsToInject.push(getActorOutput);
@@ -178,48 +210,5 @@ export async function loadToolsFromInput(
 
     // De-duplicate by tool name for safety
     const seen = new Set<string>();
-    const deduped = result.filter((entry) => !seen.has(entry.name) && seen.add(entry.name));
-
-    // Filter out openai-only tools when not in openai mode
-    const filtered = uiMode === 'openai'
-        ? deduped
-        : deduped.filter((entry) => !entry.openaiOnly);
-
-    // TODO: rework this solition as it was quickly hacked together for hotfix
-    // Deep clone except ajvValidate and call functions
-
-    // holds the original functions of the tools
-    const toolFunctions = new Map<string, { ajvValidate?: ValidateFunction<unknown>; call?:(args: InternalToolArgs) => Promise<object> }>();
-    for (const entry of filtered) {
-        if (entry.type === 'internal') {
-            toolFunctions.set(entry.name, { ajvValidate: entry.ajvValidate, call: entry.call });
-        } else {
-            toolFunctions.set(entry.name, { ajvValidate: entry.ajvValidate });
-        }
-    }
-
-    const cloned = JSON.parse(JSON.stringify(filtered, (key, value) => {
-        if (key === 'ajvValidate' || key === 'call') return undefined;
-        return value;
-    })) as ToolEntry[];
-
-    // restore the original functions
-    for (const entry of cloned) {
-        const funcs = toolFunctions.get(entry.name);
-        if (funcs) {
-            if (funcs.ajvValidate) {
-                entry.ajvValidate = funcs.ajvValidate;
-            }
-            if (entry.type === 'internal' && funcs.call) {
-                entry.call = funcs.call;
-            }
-        }
-    }
-
-    for (const entry of cloned) {
-        if (entry.name === HelperTools.ACTOR_CALL) {
-            entry.description = getCallActorDescription(uiMode);
-        }
-    }
-    return cloned;
+    return result.filter((entry) => !seen.has(entry.name) && seen.add(entry.name));
 }