refactor: split fetch-actor-details into default/openai variants (#471)

* refactor: split fetch-actor-details into default/openai variants

Extract the mode-specific branches from fetch-actor-details.ts into:
- default/fetch-actor-details.ts — full text response with output schema fetch
- openai/fetch-actor-details.ts — simplified structured content with widget metadata

Both variants import shared metadata from core/fetch-actor-details-common.ts.
The original file becomes a thin adapter that dispatches based on uiMode,
preserving the existing fetchActorDetailsTool export for categories.ts.

* refactor: split search-actors into default/openai variants (#472)

* refactor: split fetch-actor-details into default/openai variants

Extract the mode-specific branches from fetch-actor-details.ts into:
- default/fetch-actor-details.ts — full text response with output schema fetch
- openai/fetch-actor-details.ts — simplified structured content with widget metadata

Both variants import shared metadata from core/fetch-actor-details-common.ts.
The original file becomes a thin adapter that dispatches based on uiMode,
preserving the existing fetchActorDetailsTool export for categories.ts.

* refactor: split search-actors into default/openai variants

Extract the mode-specific branches from store_collection.ts into:
- default/search-actors.ts — text-based actor cards without widget metadata
- openai/search-actors.ts — widget actors with interactive widget metadata

Shared schema and metadata extracted to core/search-actors-common.ts.
The original file becomes a thin adapter that dispatches based on uiMode,
preserving the existing searchActors export for categories.ts.

* chore: remove unrelated package-lock.json changes

* refactor: split get-actor-run into default/openai variants (#473)

* refactor: split get-actor-run into default/openai variants

Extract the mode-specific branches from run.ts (getActorRun) into:
- default/get-actor-run.ts — full JSON run dump
- openai/get-actor-run.ts — abbreviated text with widget metadata

Shared schema, metadata, and data-fetching logic extracted to
core/get-actor-run-common.ts. Mode-independent tools in run.ts
(getActorRunLog, abortActorRun) are untouched. The getActorRun export
becomes a thin adapter dispatching based on uiMode.

* refactor: split call-actor into default/openai variants (#474)

* refactor: split call-actor into default/openai variants

Extract the mode-specific branches from actor.ts into:
- default/call-actor.ts — sync execution, full results, text response
- openai/call-actor.ts — forced async, widget metadata, abbreviated text

Shared args schema, MCP tool handling, actor validation, and pre-execution
pipeline extracted to core/call-actor-common.ts. The original file becomes
a thin adapter dispatching based on uiMode, preserving existing exports
(callActor, getCallActorDescription, callActorGetDataset, getActorsAsTools).

* refactor: move tools to common/openai dirs and freeze all tool definitions (Phase A) (#476)

* refactor: move mode-independent tools to common/, openai-only tools to openai/, and freeze all tool definitions

Move 11 mode-independent tool files to src/tools/common/ and 2 openai-only
internal tools to src/tools/openai/. Wrap all ~30 tool definitions with
Object.freeze() to prevent accidental mutation (e.g., Skyfire augmentation
of shared objects). The existing Skyfire code path in upsertTools() already
clones tools before mutation, so freezing originals is safe.

* refactor: add buildCategories(uiMode) and CATEGORY_NAMES (Phase B1) (#477)

* refactor: add buildCategories(uiMode) function and CATEGORY_NAMES const array

Introduce buildCategories(uiMode?) that returns mode-resolved tool variants
directly (openai tools in openai mode, default tools otherwise), eliminating
the need for runtime adapter dispatch. The same category names are used in
both modes — only the tool implementations differ.

- Add CATEGORY_NAMES const array as the single source of truth for category names
- Add ToolCategoryMap type derived from CATEGORY_NAMES
- Add buildCategories() function with mode-specific tool resolution
- Change ToolCategory type to derive from CATEGORY_NAMES instead of keyof typeof toolCategories
- Mark static toolCategories as @deprecated (will be removed when tools-loader migrates)
- Add compile-time satisfies checks via ToolCategoryMap type annotation
- Add unit tests for buildCategories: mode variants, circular-init safety, ordering

* refactor: switch tools-loader to buildCategories(uiMode), remove deep-clone hack (Phase B2) (#478)

* 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

* refactor: remove adapter files, wire direct tool variants (Phase B3) (#479)

* refactor: remove adapter files, use direct tool variants in categories

Remove the runtime-dispatching adapter layer now that buildCategories(uiMode)
resolves the correct tool variants at build time:

- Delete src/tools/actor.ts (call-actor adapter)
- Delete src/tools/store_collection.ts (search-actors adapter)
- Delete src/tools/fetch-actor-details.ts (fetch-actor-details adapter)
- Remove get-actor-run adapter from common/run.ts (keep mode-independent tools)
- Update categories.ts to use default variants directly in static toolCategories
- Update tools/index.ts to import from core modules instead of adapter

* refactor: split server-instructions into common/default/openai (Phase C) (#480)

* refactor: split server-instructions into common/default/openai modules

Split the monolithic server-instructions.ts into mode-specific modules:
- common.ts: shared instruction text (Actor overview, storage, disambiguation)
- default.ts: default mode instructions (references fetch-actor-details)
- openai.ts: UI mode instructions (workflow rules, internal tool disambiguation)
- index.ts: getServerInstructions(uiMode) selector

This eliminates if/else branching in the instructions builder. Adding a new
mode requires only a new file (e.g., anthropic.ts) and a case in index.ts.

* test: add mode-contract tests for tool separation (PR #9) (#481)

* test: add mode-contract tests for tool separation verification

* refactor: extract Skyfire augmentation and add unit tests (PR #10) (#482)

* refactor: extract Skyfire augmentation into pure function and add unit tests

- Extract applySkyfireAugmentation() from upsertTools() inline logic into src/utils/tools.ts
- Simplify upsertTools() to a 4-line loop delegating to the pure function
- Remove unused SKYFIRE_* imports from server.ts
- Add 35 unit tests covering eligibility, idempotency, frozen originals, and function preservation

* refactor: rename all files from kebab-case to snake_case (#489)

* refactor: rename all files from kebab-case to snake_case

Use git mv to rename all source files (src/, tests/, evals/, res/, scripts/)
from kebab-case to snake_case naming convention. Import paths are not yet
updated and will be fixed in the next commit.

* refactor: update all imports and references to use snake_case filenames

Fix all import paths, package.json exports/scripts, and documentation
references to match the renamed snake_case files. Add explicit NEVER
use kebab-case rule to AGENTS.md naming conventions.

* refactor: enforce one-file-per-tool in common/ directory (#491)

* refactor: split common/ multi-tool files into one file per tool

- dataset.ts → get_dataset.ts, get_dataset_items.ts, get_dataset_schema.ts
- key_value_store.ts → get_key_value_store.ts, get_key_value_store_keys.ts, get_key_value_store_record.ts
- run.ts → get_actor_run_log.ts, abort_actor_run.ts
- helpers.ts → add_actor.ts (renamed to match tool name)

* refactor: replace duplicated tool categories with unified mode-aware resolver (#494)

Replace buildCategories() + static toolCategories duplication with a single
unified category definition using mode-aware entries (ModeMap) and a generic
getCategoryTools(mode) resolver.

Key changes:
- Add ServerMode type ('default' | 'openai') as string union, normalize once
  at server construction via options.uiMode ?? 'default'
- Replace ternary mode dispatch with Record<ServerMode, ...> map lookups
  (actorExecutorsByMode, instructionsByMode)
- Add parseUiMode() boundary validator for untrusted input (URL params, env vars)
- Make mode required in all tool-resolving functions to prevent wrong-mode bugs
- Keep mode out of invariant functions (getExpectedToolNamesByCategories,
  getUnauthEnabledToolCategories, isApiTokenRequired) that never branch on mode
- Add contract test enforcing tool name invariance across modes

Author: MQ37

AGENTS.md

@@ -45,7 +45,7 @@ The codebase is organized into logical modules:
 
 - Entry points:
   - `src/index.ts` - Main library export (`ActorsMcpServer` class)
-  - `src/index-internals.ts` - Internal exports for testing and advanced usage
+  - `src/index_internals.ts` - Internal exports for testing and advanced usage
   - `src/stdio.ts` - Standard input/output entry point (CLI, used for Docker)
   - `src/main.ts` - Actor entry point (for Apify platform)
   - `src/input.ts` - Input processing and validation
@@ -195,7 +195,7 @@ We use **4 spaces** for indentation (configured in `.editorconfig`).
 - **Constants**: Use uppercase `SNAKE_CASE` for global, immutable constants (e.g., `ACTOR_MAX_MEMORY_MBYTES`, `SERVER_NAME`)
 - **Functions & Variables**: Use `camelCase` format (e.g., `fetchActorDetails`, `actorClient`)
 - **Classes, Types, Interfaces**: Use `PascalCase` format (e.g., `ActorsMcpServer`, `ActorDetailsResult`)
-- **Files & Folders**: Use lowercase `snake_case` format (e.g., `actor_details.ts`, `key_value_store.ts`)
+- **Files & Folders**: Use lowercase `snake_case` format (e.g., `actor_details.ts`, `key_value_store.ts`). **NEVER use kebab-case** (`kebab-case.ts`) for file or folder names — always use underscores, not hyphens.
 - **Booleans**: Prefix with `is`, `has`, or `should` (e.g., `isValid`, `hasFinished`, `shouldRetry`)
 - **Units**: Suffix with the unit of measure (e.g., `intervalMillis`, `maxMemoryBytes`)
 - **Date/Time**: Suffix with `At` (e.g., `createdAt`, `updatedAt`)
@@ -283,10 +283,10 @@ We use **4 spaces** for indentation (configured in `.editorconfig`).
 ### Common patterns
 
 - **Tool implementation**: Tools are defined in `src/tools/` using Zod schemas for validation
-- **Actor interaction**: Use `src/utils/apify-client.ts` for Apify API calls, never call Apify API directly
+- **Actor interaction**: Use `src/utils/apify_client.ts` for Apify API calls, never call Apify API directly
 - **Error responses**: Return user-friendly error messages with suggestions
 - **Input validation**: Always validate tool inputs with Zod before processing
-- **Caching**: Use TTL-based caching for Actor schemas and details (see `src/utils/ttl-lru.ts`)
+- **Caching**: Use TTL-based caching for Actor schemas and details (see `src/utils/ttl_lru.ts`)
 - **Constants and Tool Names**: Always use constants and never magic or hardcoded values. When referring to tools, ALWAYS use the `HelperTools` enum.
   - **Exception**: Integration tests (`tests/integration/`) must use hardcoded strings for tool names. This ensures tests fail if a tool is renamed, helping to prevent accidental breaking changes.
 

DEVELOPMENT.md

@@ -29,7 +29,7 @@ tests/
 Key entry points:
 
 - `src/index.ts` - Main library export (`ActorsMcpServer` class)
-- `src/index-internals.ts` - Internal exports for testing / advanced usage
+- `src/index_internals.ts` - Internal exports for testing / advanced usage
 - `src/stdio.ts` - Standard input/output (CLI) entry point
 - `src/main.ts` - Actor entry point (standby server / debugging)
 - `src/input.ts` - Input processing and validation

evals/2025-11-04-failed-cases-analysis.md evals/2025_11_04_failed_cases_analysis.mdevals/2025-11-04-failed-cases-analysis.md renamed to evals/2025_11_04_failed_cases_analysis.md

@@ -15,7 +15,7 @@ import { hideBin } from 'yargs/helpers';
 import log from '@apify/log';
 
 import { sanitizeHeaderValue, validatePhoenixEnvVars } from './config.js';
-import { loadTestCases, filterByCategory, filterById, type TestCase } from './evaluation-utils.js';
+import { loadTestCases, filterByCategory, filterById, type TestCase } from './evaluation_utils.js';
 
 // Set log level to debug
 log.setLevel(log.LEVELS.INFO);

evals/create-dataset.ts evals/create_dataset.tsevals/create-dataset.ts renamed to evals/create_dataset.ts

@@ -8,7 +8,7 @@ import {
     createToolSelectionLLMEvaluator,
     loadTestCases, filterById,
     type TestCase
-} from './evaluation-utils.js';
+} from './evaluation_utils.js';
 import { PASS_THRESHOLD, sanitizeHeaderValue } from './config.js';
 
 dotenv.config({ path: '.env' });

evals/eval-single.ts evals/eval_single.tsevals/eval-single.ts renamed to evals/eval_single.ts

@@ -9,8 +9,8 @@ import { createClassifierFn } from '@arizeai/phoenix-evals';
 
 import log from '@apify/log';
 
-import { ApifyClient } from '../src/apify-client.js';
-import { getToolPublicFieldOnly, processParamsGetTools } from '../src/index-internals.js';
+import { ApifyClient } from '../src/apify_client.js';
+import { getToolPublicFieldOnly, processParamsGetTools } from '../src/index_internals.js';
 import type { ToolBase, ToolEntry } from '../src/types.js';
 import {
     SYSTEM_PROMPT,
@@ -20,16 +20,16 @@ import {
     TEMPERATURE,
     sanitizeHeaderValue
 } from './config.js';
-import { loadTestCases as loadTestCasesShared, filterByCategory, filterById } from './shared/test-case-loader.js';
-import { transformToolsToOpenAIFormat } from './shared/openai-tools.js';
+import { loadTestCases as loadTestCasesShared, filterByCategory, filterById } from './shared/test_case_loader.js';
+import { transformToolsToOpenAIFormat } from './shared/openai_tools.js';
 import type { ToolSelectionTestCase, TestData } from './shared/types.js';
 
 // Re-export types for backwards compatibility
 export type TestCase = ToolSelectionTestCase;
 export type { TestData } from './shared/types.js';
 
 // Re-export shared functions for backwards compatibility
-export { filterByCategory, filterById } from './shared/test-case-loader.js';
+export { filterByCategory, filterById } from './shared/test_case_loader.js';
 
 type ExampleInputOnly = { input: Record<string, unknown>, metadata?: Record<string, unknown>, output?: never };
 

evals/evaluation-utils.ts evals/evaluation_utils.tsevals/evaluation-utils.ts renamed to evals/evaluation_utils.ts

@@ -20,7 +20,7 @@ import {
     loadTools,
     createOpenRouterTask,
     createToolSelectionLLMEvaluator
-} from './evaluation-utils.js';
+} from './evaluation_utils.js';
 import {
     DATASET_NAME,
     MODELS_TO_EVALUATE,

evals/run-evaluation.ts evals/run_evaluation.tsevals/run-evaluation.ts renamed to evals/run_evaluation.ts

@@ -2,7 +2,7 @@
  * Filter test cases by line ranges
  */
 
-import type { LineRange } from './line-range-parser.js';
+import type { LineRange } from './line_range_parser.js';
 
 /**
  * Type for test cases with line number metadata