fix: compose client-agnostic tools eagerly so recovery restores them

The gating refactor made ALL helper-tool composition wait for the client
(clientKnown), which broke the recovery contract: a node that restores a
session via loadToolsByName without receiving an initialize (see
tests/integration/internals.test.ts "load and restore tools from a tool
list") silently lost every internal helper, since they sat in the
pending queue and were never flushed.

Split the two concerns that were conflated:
- Mode-unresolved ('auto' before initialize): still defer the whole
  source — composing with the preliminary DEFAULT mode would pick wrong
  (non-widget) variants. This restores serverModeResolved as the
  compose-vs-defer gate.
- Client-unknown: only withhold client-gated tools (report-problem) via
  isToolServable/isClientGatedTool; client-agnostic tools compose
  immediately, so explicit-mode recovery restores them without an
  initialize. The initialize flush re-composes and adds the gated tools
  once the client is known.

Adds a unit test for the recovery case. Also renames the stale
getServerInstructions `feedbackAvailable` param and fixes two stale
comments left by the rename/gating commits.

Claude-Session: https://claude.ai/code/session_01TV4x9VgMCvXGF7TftskLAn

Author: RobertCrupa

src/mcp/server.ts

@@ -91,7 +91,7 @@ import {
     computeToolResponseBytes,
     getToolCallErrorUserText,
 } from '../utils/mcp.js';
-import { isToolBlockedForClient } from '../utils/mcp_clients.js';
+import { isClientGatedTool, isToolBlockedForClient } from '../utils/mcp_clients.js';
 import { buildPaymentRequiredResponse, isX402PaymentRequiredError } from '../utils/payment_errors.js';
 import { createProgressTracker } from '../utils/progress.js';
 import { getServerInstructions } from '../utils/server-instructions/index.js';
@@ -193,13 +193,17 @@ export class ActorsMcpServer {
      * values bypass auto-detect.
      */
     private readonly serverModeOption: ServerModeOption;
+    /** True once the server mode is final: at construction for explicit `default`/`apps`, or after
+     *  the initialize handler resolves `'auto'`. Composing before this in `'auto'` mode would use
+     *  the preliminary DEFAULT mode and produce the wrong (non-widget) tool variants, so composition
+     *  waits for it. Distinct from {@link clientKnown}, which only withholds client-gated tools. */
+    private serverModeResolved: boolean;
     /**
-     * Tool requests queued until the connecting client is known. Client-dependent composition
-     * (helper tools, per-client blocklist) is deferred to the initialize handler because MCP
-     * guarantees no `tools/list` before `initialize`. Actor tools are upserted immediately
-     * (client-agnostic); we also capture the exact actor-tool slice fetched for each request so
-     * the flush composes every entry against *its own* actor list rather than the accumulated
-     * union across unrelated requests.
+     * Tool sources queued until composition is possible. Enqueued when the mode is not yet resolved
+     * (`'auto'` before initialize), and re-composed by the initialize flush — which is also when the
+     * client becomes known, so any client-gated tools withheld by an eager compose are added then.
+     * We capture the exact actor-tool slice fetched for each request so the flush composes every
+     * entry against *its own* actor list rather than the accumulated union across unrelated requests.
      */
     private pendingToolsUntilClientKnown: { input: Input; actorTools: ToolEntry[] }[] = [];
 
@@ -237,6 +241,7 @@ export class ActorsMcpServer {
         // Preliminary resolution — re-resolved inside the initialize handler once
         // client capabilities are known (only for 'auto').
         this.serverMode = resolveServerMode(this.serverModeOption, false);
+        this.serverModeResolved = this.serverModeOption !== 'auto';
 
         const { setupSigintHandler = true } = options;
         this.server = new Server(getServerInfo(), {
@@ -329,6 +334,7 @@ export class ActorsMcpServer {
                 if (resolved !== this.serverMode) {
                     this.serverMode = resolved;
                 }
+                this.serverModeResolved = true;
             }
 
             // Setting this makes `clientKnown` true, so the queued compose below (and any later
@@ -356,30 +362,38 @@ export class ActorsMcpServer {
     }
 
     /** True once the connecting client is known (set in the initialize handler, or hydrated by a
-     *  recovery path). Client-dependent tool composition must wait for this so the per-client
-     *  blocklist can be applied at the single compose choke point. */
+     *  recovery path). Only client-gated tools wait for this so the per-client blocklist can be
+     *  applied; client-agnostic tools compose regardless. */
     private get clientKnown(): boolean {
         return this.options.initializeRequestData != null;
     }
 
     /**
-     * Compose the final tool list for the current client: resolve mode-specific tools, then drop
-     * any that are not servable for this connection (see {@link isToolServable}). The single choke
-     * point for client gating — used by both the initialize flush and post-init loads (e.g.
-     * recovery), so a blocked tool can never slip in via a late load. Never filters actor tools
-     * (they are always servable); safe to call before or after the client is known.
+     * Compose the tool list for the current connection: resolve mode-specific tools, then drop any
+     * not currently servable (see {@link isToolServable}). Client-agnostic tools compose eagerly, so
+     * a recovery/rehydration load without an initialize still restores them. Client-gated tools are
+     * withheld until the client is known and re-added by the initialize flush. Used by every
+     * input-driven load path and the flush. (loadActorsAsTools upserts actor tools directly; actor
+     * tools are never client-gated, so they need no filtering.)
      */
     private composeToolsForClient(input: Input, actorTools: ToolEntry[]): ToolEntry[] {
         return getToolsForServerMode(input, actorTools, this.serverMode).filter((tool) =>
             this.isToolServable(tool.name),
         );
     }
 
-    /** Whether a tool may be served on this connection: not blocklisted for the client, and — for
-     *  report-problem, whose only function is forwarding submissions via telemetry — only when
-     *  telemetry is enabled (otherwise it would just fake an acknowledgement into the void). */
+    /**
+     * Whether a tool may be served on this connection right now:
+     * - report-problem's only function is forwarding submissions via telemetry, so it is never
+     *   servable when telemetry is disabled (it would just fake an acknowledgement into the void).
+     * - A client-gated tool (has a {@link TOOL_CLIENT_BLOCKLIST} rule) cannot be judged until the
+     *   client is known, so it is withheld until then — the initialize flush re-composes and adds it
+     *   if the client allows. Client-agnostic tools are always servable, so they compose eagerly and
+     *   survive a recovery load that never sees an initialize.
+     */
     private isToolServable(toolName: string): boolean {
         if (toolName === HELPER_TOOLS.PROBLEM_REPORT && !this.telemetryEnabled) return false;
+        if (isClientGatedTool(toolName) && !this.clientKnown) return false;
         return !isToolBlockedForClient(toolName, this.options.initializeRequestData);
     }
 
@@ -392,11 +406,10 @@ export class ActorsMcpServer {
 
         this.pendingToolsUntilClientKnown = [];
 
-        // Notify after the flush so shared-state handlers (e.g. Redis recovery) see
-        // the final tool set, including mode-specific helpers added here. Pre-init,
-        // `loadToolsByName` may have fired `upsertTools(actorTools, true)` with actor
-        // tools only (helpers still queued), and `loadToolsFromUrl` / `loadToolsFromInput`
-        // don't notify at all — this call reconciles both paths to the complete set.
+        // Notify after the flush so shared-state handlers (e.g. Redis recovery) see the final tool
+        // set. Load paths already upserted the client-agnostic tools pre-init; re-upserting is
+        // idempotent, and this pass adds the client-gated tools (e.g. report-problem) now that the
+        // client is known, reconciling shared state to the complete set.
         if (tools.length > 0) this.upsertTools(tools, true);
     }
 
@@ -491,16 +504,21 @@ export class ActorsMcpServer {
             paymentProvider: this.options.paymentProvider,
         });
 
-        if (!this.clientKnown) {
+        // 'auto' before initialize: mode not final — composing now would pick wrong variants, so
+        // defer the whole source to the initialize flush (actor tools are mode-agnostic, upsert now).
+        if (!this.serverModeResolved) {
             this.pendingToolsUntilClientKnown.push({ input: restoreInput, actorTools });
             if (actorTools.length > 0) this.upsertTools(actorTools, true);
             return;
         }
-
+        // Mode is final: compose eagerly so client-agnostic tools restore even without an initialize
+        // (recovery / rehydration). Client-gated tools are withheld until the client is known; queue
+        // the source so the initialize flush re-composes and adds them.
         const toolsToLoad = this.composeToolsForClient(restoreInput, actorTools);
         if (toolsToLoad.length > 0) {
             this.upsertTools(toolsToLoad, actorTools.length > 0);
         }
+        if (!this.clientKnown) this.pendingToolsUntilClientKnown.push({ input: restoreInput, actorTools });
     }
 
     /**
@@ -528,10 +546,10 @@ export class ActorsMcpServer {
             paymentProvider: this.options.paymentProvider,
         });
 
-        if (!this.clientKnown) {
+        if (!this.serverModeResolved) {
             this.pendingToolsUntilClientKnown.push({ input, actorTools });
             if (actorTools.length > 0) {
-                log.debug('Loading actor tools from query parameters before the client is known');
+                log.debug('Loading actor tools from query parameters before mode resolution');
                 this.upsertTools(actorTools, false);
             }
             return;
@@ -542,12 +560,14 @@ export class ActorsMcpServer {
             log.debug('Loading tools from query parameters');
             this.upsertTools(tools, false);
         }
+        if (!this.clientKnown) this.pendingToolsUntilClientKnown.push({ input, actorTools });
     }
 
     /**
      * Two-phase: getActors (async, client-agnostic Apify fetch) then composeToolsForClient
-     * (sync, client-dependent compose). When the client is not yet known, queue actorTools and
-     * let the initialize handler compose them later.
+     * (sync compose + servability filter). If the mode isn't resolved yet ('auto' before initialize)
+     * the whole source is queued for the flush. Otherwise tools compose immediately; client-gated
+     * tools are withheld until the client is known, and the source is queued so the flush adds them.
      *
      * Don't move the getActors await into the initialize handler — clients time out
      * waiting for InitializeResult. The queue buffers already-fetched data, not network
@@ -558,13 +578,14 @@ export class ActorsMcpServer {
             actorStore: this.actorStore,
             paymentProvider: this.options.paymentProvider,
         });
-        if (!this.clientKnown) {
+        if (!this.serverModeResolved) {
             this.pendingToolsUntilClientKnown.push({ input, actorTools });
             if (actorTools.length > 0) this.upsertTools(actorTools);
             return;
         }
         const tools = this.composeToolsForClient(input, actorTools);
         if (tools.length > 0) this.upsertTools(tools);
+        if (!this.clientKnown) this.pendingToolsUntilClientKnown.push({ input, actorTools });
     }
 
     /** Delete tools from the server and notify the handler.
@@ -874,8 +895,8 @@ export class ActorsMcpServer {
             let toolResult: unknown = null;
             const captureResult = <T>(r: T): T => {
                 // On a failed result, nudge the agent to report the blocker via report-problem at the
-                // moment it decides what to do next. Gated on the tool actually being served, so
-                // Anthropic clients (hard-blocked) and feedback-off selections never see it.
+                // moment it decides what to do next. Gated on the tool actually being served (see
+                // isToolServable), so clients where it is blocklisted or telemetry is off never see it.
                 const augmented = appendReportProblemNudge(r, {
                     failingToolName: resolvedToolName,
                     available: this.tools.has(HELPER_TOOLS.PROBLEM_REPORT),

src/utils/mcp_clients.ts

@@ -17,6 +17,15 @@ export function isToolBlockedForClient(toolName: string, initializeRequestData?:
     return blockedClients.some((blocked) => clientName.includes(blocked));
 }
 
+/**
+ * True when `toolName` has any client-gating rule in {@link TOOL_CLIENT_BLOCKLIST}. Such a tool
+ * cannot be judged until the connecting client is known, so composition withholds it until then;
+ * tools with no rule are client-agnostic and compose immediately.
+ */
+export function isClientGatedTool(toolName: string): boolean {
+    return TOOL_CLIENT_BLOCKLIST[toolName] !== undefined;
+}
+
 /**
  * Determines if the MCP client supports dynamic tools based on the InitializeRequest data.
  */

src/utils/server-instructions/index.ts

@@ -14,12 +14,12 @@ import { SERVER_MODE } from '../../types.js';
  * Build server instructions for the given mode.
  *
  * Apps-only sections are omitted in default mode to prevent models from
- * attempting to call widget tools that are not registered. The feedback section is
- * emitted only when `feedbackAvailable` is true — i.e. `report-problem` is actually
- * served — so clients that never receive the tool (Anthropic surfaces, or a tool
- * selection that excludes the `report-problem` category) are not told to call it.
+ * attempting to call widget tools that are not registered. The report-problem line is
+ * emitted only when `reportProblemAvailable` is true — i.e. `report-problem` is actually
+ * served — so clients that never receive the tool (Anthropic surfaces, telemetry off, or a
+ * tool selection that excludes the `report-problem` category) are not told to call it.
  */
-export function getServerInstructions(mode: SERVER_MODE = SERVER_MODE.DEFAULT, feedbackAvailable = false): string {
+export function getServerInstructions(mode: SERVER_MODE = SERVER_MODE.DEFAULT, reportProblemAvailable = false): string {
     const isApps = mode === SERVER_MODE.APPS;
 
     return `
@@ -87,7 +87,7 @@ ${
 - **Dedicated Actor tools (e.g. ${RAG_WEB_BROWSER}) vs \`${HELPER_TOOLS.ACTOR_CALL}\`:**
   Prefer dedicated tools when available; use \`${HELPER_TOOLS.ACTOR_CALL}\` only when no specialized tool exists in the Apify store.
 ${
-    feedbackAvailable
+    reportProblemAvailable
         ? `
 If a tool or Actor fails and you cannot resolve it, you can report it with \`${HELPER_TOOLS.PROBLEM_REPORT}\`.
 `

tests/unit/mcp.server.report_problem_gating.test.ts

@@ -110,4 +110,16 @@ describe('report-problem client gating', () => {
 
         expect(server.tools.has(HELPER_TOOLS.PROBLEM_REPORT)).toBe(false);
     });
+
+    // Only client-gated tools wait for the client; everything else must load eagerly, or a
+    // recovery/rehydration node that restores tools via loadToolsByName without ever receiving an
+    // initialize would silently lose all its helper tools.
+    it('restores client-agnostic helper tools loaded before any initialize', async () => {
+        const server = track(makeServer());
+
+        await server.loadToolsByName([HELPER_TOOLS.ACTOR_RUNS_GET, HELPER_TOOLS.DATASET_GET_ITEMS], {} as never);
+
+        expect(server.tools.has(HELPER_TOOLS.ACTOR_RUNS_GET)).toBe(true);
+        expect(server.tools.has(HELPER_TOOLS.DATASET_GET_ITEMS)).toBe(true);
+    });
 });