refactor: simplify tool types using discriminated unions

MQ37 · MQ37 · commit bfc820d432b6 · 2025-10-31T14:19:37.000-07:00
- Convert ToolEntry to discriminated union with explicit type variants
  - HelperToolEntry: type: 'internal'
  - ActorToolEntry: type: 'actor'
  - ActorMcpToolEntry: type: 'actor-mcp'
- Remove actorFullName from all internal tools (11 tools across 9 files)
- Remove unused ToolType export
- Improves type safety and enables automatic type narrowing in TypeScript
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
@@ -329,7 +329,6 @@ export const callActor: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_CALL,
-        actorFullName: HelperTools.ACTOR_CALL,
         description: `Call any Actor from the Apify Store using a mandatory two-step workflow.
 This ensures you first get the Actor’s input schema and details before executing it safely.
 
diff --git a/src/tools/build.ts b/src/tools/build.ts
@@ -110,8 +110,6 @@ export const actorDefinitionTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_GET_DETAILS,
-        // TODO: remove actorFullName from internal tools
-        actorFullName: HelperTools.ACTOR_GET_DETAILS,
         description: 'Get documentation, readme, input schema and other details about an Actor. '
             + 'For example, when user says, I need to know more about web crawler Actor.'
             + 'Get details for an Actor with with Actor ID or Actor full name, i.e. username/name.'
diff --git a/src/tools/dataset.ts b/src/tools/dataset.ts
@@ -45,7 +45,6 @@ export const getDataset: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.DATASET_GET,
-        actorFullName: HelperTools.DATASET_GET,
         description: `Get metadata for a dataset (collection of structured data created by an Actor run).
 The results will include dataset details such as itemCount, schema, fields, and stats.
 Use fields to understand structure for filtering with ${HelperTools.DATASET_GET_ITEMS}.
@@ -79,7 +78,6 @@ export const getDatasetItems: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.DATASET_GET_ITEMS,
-        actorFullName: HelperTools.DATASET_GET_ITEMS,
         description: `Retrieve dataset items with pagination, sorting, and field selection.
 Use clean=true to skip empty items and hidden fields. Include or omit fields using comma-separated lists.
 For nested objects, first flatten them (e.g., flatten="metadata"), then reference nested fields via dot notation (e.g., fields="metadata.url").
@@ -143,7 +141,6 @@ export const getDatasetSchema: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.DATASET_SCHEMA_GET,
-        actorFullName: HelperTools.DATASET_SCHEMA_GET,
         description: `Generate a JSON schema from a sample of dataset items.
 The schema describes the structure of the data and can be used for validation, documentation, or processing.
 Use this to understand the dataset before fetching many items.
diff --git a/src/tools/dataset_collection.ts b/src/tools/dataset_collection.ts
@@ -29,7 +29,6 @@ export const getUserDatasetsList: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.DATASET_LIST_GET,
-        actorFullName: HelperTools.DATASET_LIST_GET,
         description: `List datasets (collections of Actor run data) for the authenticated user.
 Actor runs automatically produce unnamed datasets (set unnamed=true to include them). Users can also create named datasets.
 
diff --git a/src/tools/get-actor-output.ts b/src/tools/get-actor-output.ts
@@ -67,7 +67,6 @@ export const getActorOutput: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_OUTPUT_GET,
-        actorFullName: HelperTools.ACTOR_OUTPUT_GET,
         description: `Retrieve the output dataset items of a specific Actor run using its datasetId.
 You can select specific fields to return (supports dot notation like "crawl.statusCode") and paginate results with offset and limit.
 This tool is a simplified version of the get-dataset-items tool, focused on Actor run outputs.
diff --git a/src/tools/get-html-skeleton.ts b/src/tools/get-html-skeleton.ts
@@ -40,7 +40,6 @@ export const getHtmlSkeleton: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.GET_HTML_SKELETON,
-        actorFullName: HelperTools.GET_HTML_SKELETON,
         description: `Retrieve the HTML skeleton (clean structure) of a webpage by stripping scripts, styles, and non-essential attributes.
 This keeps the core HTML structure, links, images, and data attributes for analysis. Supports optional JavaScript rendering for dynamic pages.
 
diff --git a/src/tools/key_value_store.ts b/src/tools/key_value_store.ts
@@ -19,7 +19,6 @@ export const getKeyValueStore: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.KEY_VALUE_STORE_GET,
-        actorFullName: HelperTools.KEY_VALUE_STORE_GET,
         description: `Get details about a key-value store by ID or username~store-name.
 The results will include store metadata (ID, name, owner, access settings) and usage statistics.
 
@@ -61,7 +60,6 @@ export const getKeyValueStoreKeys: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.KEY_VALUE_STORE_KEYS_GET,
-        actorFullName: HelperTools.KEY_VALUE_STORE_KEYS_GET,
         description: `List keys in a key-value store with optional pagination.
 The results will include keys and basic info about stored values (e.g., size).
 Use exclusiveStartKey and limit to paginate.
@@ -103,7 +101,6 @@ export const getKeyValueStoreRecord: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.KEY_VALUE_STORE_RECORD_GET,
-        actorFullName: HelperTools.KEY_VALUE_STORE_RECORD_GET,
         description: `Get a value stored in a key-value store under a specific key.
 The response preserves the original Content-Encoding; most clients handle decompression automatically.
 
diff --git a/src/tools/key_value_store_collection.ts b/src/tools/key_value_store_collection.ts
@@ -29,7 +29,6 @@ export const getUserKeyValueStoresList: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.KEY_VALUE_STORE_LIST_GET,
-        actorFullName: HelperTools.KEY_VALUE_STORE_LIST_GET,
         description: `List key-value stores owned by the authenticated user.
 Actor runs automatically produce unnamed stores (set unnamed=true to include them). Users can also create named stores.
 
diff --git a/src/tools/run.ts b/src/tools/run.ts
@@ -26,7 +26,6 @@ export const getActorRun: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_RUNS_GET,
-        actorFullName: HelperTools.ACTOR_RUNS_GET,
         description: `Get detailed information about a specific Actor run by runId.
 The results will include run metadata (status, timestamps), performance stats, and resource IDs (datasetId, keyValueStoreId, requestQueueId).
 
@@ -67,7 +66,6 @@ export const getActorRunLog: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_RUNS_LOG,
-        actorFullName: HelperTools.ACTOR_RUNS_LOG,
         description: `Retrieve recent log lines for a specific Actor run.
 The results will include the last N lines of the run’s log output (plain text).
 
@@ -98,7 +96,6 @@ export const abortActorRun: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_RUNS_ABORT,
-        actorFullName: HelperTools.ACTOR_RUNS_ABORT,
         description: `Abort an Actor run that is currently starting or running.
 For runs with status FINISHED, FAILED, ABORTING, or TIMED-OUT, this call has no effect.
 The results will include the updated run details after the abort request.
diff --git a/src/tools/run_collection.ts b/src/tools/run_collection.ts
@@ -29,7 +29,6 @@ export const getUserRunsList: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_RUN_LIST_GET,
-        actorFullName: HelperTools.ACTOR_RUN_LIST_GET,
         description: `List Actor runs for the authenticated user with optional filtering and sorting.
 The results will include run details (including datasetId and keyValueStoreId) and can be filtered by status.
 Valid statuses: READY (not allocated), RUNNING (executing), SUCCEEDED (finished), FAILED (failed), TIMING-OUT, TIMED-OUT, ABORTING, ABORTED.
diff --git a/src/types.ts b/src/types.ts
@@ -142,20 +142,48 @@ export interface ActorMcpTool extends ToolBase {
 }
 
 /**
- * Type discriminator for tools - indicates whether a tool is internal or Actor-based.
+ * Discriminated union for Helper (internal) tools.
+ * These are tools implemented directly in the MCP server.
  */
-export type ToolType = 'internal' | 'actor' | 'actor-mcp';
+export interface HelperToolEntry {
+    /** Type discriminator for helper/internal tools */
+    type: 'internal';
+    /** The helper tool instance */
+    tool: HelperTool;
+}
+
+/**
+ * Discriminated union for Actor tools.
+ * These are tools that wrap Apify Actors.
+ */
+export interface ActorToolEntry {
+    /** Type discriminator for actor tools */
+    type: 'actor';
+    /** The actor tool instance */
+    tool: ActorTool;
+}
+
+/**
+ * Discriminated union for Actor MCP tools.
+ * These are tools from Actorized MCP servers that this server proxies.
+ */
+export interface ActorMcpToolEntry {
+    /** Type discriminator for actor MCP tools */
+    type: 'actor-mcp';
+    /** The actor MCP tool instance */
+    tool: ActorMcpTool;
+}
 
 /**
  * Wrapper interface that combines a tool with its type discriminator.
  * Used to store and manage tools of different types uniformly.
+ * 
+ * This is a discriminated union that ensures type safety:
+ * - When type is 'internal', tool is guaranteed to be HelperTool
+ * - When type is 'actor', tool is guaranteed to be ActorTool
+ * - When type is 'actor-mcp', tool is guaranteed to be ActorMcpTool
  */
-export interface ToolEntry {
-    /** Type of the tool (internal or actor) */
-    type: ToolType;
-    /** The tool instance */
-    tool: ActorTool | HelperTool | ActorMcpTool;
-}
+export type ToolEntry = HelperToolEntry | ActorToolEntry | ActorMcpToolEntry;
 
 /**
  * Price for a single event in a specific tier.
