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