Refactor debug MCP tools: shared projections, registry helpers, doc updates

Tier 1 cleanup based on PR review feedback (patricksullivansf, yhsieh1)
and self-review.

DRY:
- Extract shared projection helpers to SDK (projections.ts):
  truncateValue, isPrimitiveType, projectFrame, projectVariable,
  projectBreakpoint, projectThreadLocation, plus exported types
  MappedFrame/MappedVariable/MappedBreakpoint/MappedLocation. Used by
  both MCP debug tools and CLI RPC mode — eliminates 5+ copies of the
  same projection code and the MAX_VALUE_LENGTH/PRIMITIVE_TYPES
  constants.
- Add getSessionEntry/getRegistry helpers to session-registry. Replace
  the 4-line "registry not available" + getSessionOrThrow boilerplate
  in 11 tools.
- Move halt-waiter promise pattern into DebugSessionRegistry.waitForHalt.
  Used by debug_wait_for_stop and debug_capture_at_breakpoint instead
  of duplicating the promise/timer/cleanup logic.
- Replace step-action switch with a lookup map.

API:
- DebugSessionRegistry.registerSession now takes an options object
  (yhsieh1 nit) instead of 5 positional parameters.

Docs:
- Add "Recovery from broken or orphaned sessions" section to
  docs/mcp/tools/diagnostics.md (patricksullivansf concern).
- Link to main authentication and configuration guides.
- Add JSDoc to ServerContext explaining stdio-per-client isolation
  vs shared transport caveats (patricksullivansf concern).

Tool descriptions (yhsieh1 audit):
- Drop user-facing prose, sharpen for agent consumption.
- debug_start_session: explicitly mention SFRA controllers, custom API
  scripts, hooks, jobs as use cases.
- debug_end_session: IMPORTANT call-out to always end sessions.

Coverage stays at 99.81% statements/lines, 94.81% branches,
98.93% functions — all above thresholds.

Author: clavery

docs/mcp/tools/diagnostics.md

@@ -4,13 +4,25 @@ description: MCP tools for script debugging on B2C Commerce instances.
 
 # Diagnostics Tools
 
-MCP tools for connecting to the B2C Commerce Script Debugger API (SDAPI), setting breakpoints, inspecting variables, and stepping through server-side code. These tools are available in the **CARTRIDGES**, **SCAPI**, and **STOREFRONTNEXT** toolsets.
+MCP tools for connecting to the B2C Commerce Script Debugger API (SDAPI), setting breakpoints, inspecting variables, and stepping through server-side code. These tools are available in the **CARTRIDGES** and **SCAPI** toolsets.
 
 ## Authentication
 
 All debug tools require **Basic Auth** credentials (username and password) for a Business Manager user with the `WebDAV_Manage_Customization` permission.
 
-The script debugger must be enabled on the instance: Business Manager > Administration > Development Configuration > Script Debugger > Enable.
+The script debugger must also be enabled on the instance: Business Manager > Administration > Development Configuration > Script Debugger > Enable.
+
+See the [Authentication guide](../../guide/authentication) and [Configuration guide](../../guide/configuration) for credential setup details.
+
+## Recovery from broken or orphaned sessions
+
+Debug sessions are stateful and live in the MCP server process. If the agent loses track of an active session (context flush, crash, restart), or breakpoints stop firing as expected:
+
+1. **List active sessions** — call `debug_list_sessions` (no args). It returns all sessions known to the server with their `session_id`, `hostname`, halted threads, and currently armed breakpoints.
+2. **End orphaned sessions** — call `debug_end_session` with the `session_id` to free the debugger slot on the instance.
+3. **SDAPI single-client guarantee** — the script debugger only supports one client per `client_id` per host. Calling `debug_start_session` with the same `client_id` against the same host implicitly takes over (replaces) any prior client. This is the safety net when a session is lost without a clean shutdown.
+4. **Idle cleanup** — sessions inactive for 30 minutes are automatically cleaned up by the server.
+5. **Restart the MCP server** — as a last resort, restarting the MCP server destroys all session state. The orphaned debugger slot on the instance will be freed by SDAPI's own 60-second halt-timeout or by the next `debug_start_session` with the same client ID.
 
 ---
 

packages/b2c-cli/src/utils/debug/rpc.ts

@@ -12,9 +12,13 @@ import type {
   SourceMapper,
 } from '@salesforce/b2c-tooling-sdk/operations/debug';
 import type {CartridgeMapping} from '@salesforce/b2c-tooling-sdk/operations/code';
-import {resolveBreakpointPath} from '@salesforce/b2c-tooling-sdk/operations/debug';
-
-const MAX_VALUE_LENGTH = 200;
+import {
+  projectBreakpoint,
+  projectFrame,
+  projectThreadLocation,
+  projectVariable,
+  resolveBreakpointPath,
+} from '@salesforce/b2c-tooling-sdk/operations/debug';
 
 interface RpcRequest {
   id?: number | string;
@@ -63,18 +67,9 @@ export class DebugRpc {
     this.currentThreadId = thread.id;
     this.currentFrameIndex = 0;
 
-    const topFrame = thread.call_stack?.[0];
-    const loc = topFrame?.location;
     this.emitEvent('thread_stopped', {
       thread_id: thread.id,
-      location: loc
-        ? {
-            file: this.sourceMapper.toLocalPath(loc.script_path) ?? null,
-            line: loc.line_number,
-            function_name: loc.function_name,
-            script_path: loc.script_path,
-          }
-        : null,
+      location: projectThreadLocation(thread, this.sourceMapper),
     });
   }
 
@@ -113,13 +108,13 @@ export class DebugRpc {
   private async handleCommand(command: string, args: Record<string, unknown>): Promise<unknown> {
     switch (command) {
       case 'continue': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         await this.manager.resume(threadId);
         return {thread_id: threadId, status: 'resumed'};
       }
 
       case 'evaluate': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         const frameIndex = (args.frame_index as number) ?? this.currentFrameIndex;
         const expression = args.expression as string;
         if (!expression) throw new Error('Missing required arg: expression');
@@ -128,86 +123,45 @@ export class DebugRpc {
       }
 
       case 'get_stack': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         const thread = await this.manager.client.getThread(threadId);
         return {
           thread_id: thread.id,
-          frames: thread.call_stack.map((frame) => ({
-            index: frame.index,
-            function_name: frame.location.function_name,
-            file: this.sourceMapper.toLocalPath(frame.location.script_path) ?? null,
-            line: frame.location.line_number,
-            script_path: frame.location.script_path,
-          })),
+          frames: thread.call_stack.map((frame) => projectFrame(frame, this.sourceMapper)),
         };
       }
 
       case 'get_variables': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         const frameIndex = (args.frame_index as number) ?? this.currentFrameIndex;
         const objectPath = args.object_path as string | undefined;
 
         if (objectPath) {
           const result = await this.manager.client.getMembers(threadId, frameIndex, objectPath);
-          return {
-            variables: result.object_members.map((m) => ({
-              name: m.name,
-              type: m.type,
-              value: truncateValue(m.value),
-              has_children: !isPrimitive(m.type),
-            })),
-          };
+          return {variables: result.object_members.map((m) => projectVariable(m, {includeScope: false}))};
         }
 
         const result = await this.manager.client.getVariables(threadId, frameIndex);
-        let members = result.object_members;
-        if (args.scope) {
-          members = members.filter((m) => m.scope === args.scope);
-        }
-        return {
-          variables: members.map((m) => ({
-            name: m.name,
-            type: m.type,
-            value: truncateValue(m.value),
-            scope: m.scope,
-            has_children: !isPrimitive(m.type),
-          })),
-        };
+        const members = args.scope
+          ? result.object_members.filter((m) => m.scope === args.scope)
+          : result.object_members;
+        return {variables: members.map((m) => projectVariable(m))};
       }
 
       case 'list_breakpoints': {
         const bps = await this.manager.client.getBreakpoints();
-        return {
-          breakpoints: bps.map((bp) => ({
-            id: bp.id,
-            file: this.sourceMapper.toLocalPath(bp.script_path) ?? null,
-            line: bp.line_number,
-            script_path: bp.script_path,
-            condition: bp.condition,
-          })),
-        };
+        return {breakpoints: bps.map((bp) => projectBreakpoint(bp, this.sourceMapper))};
       }
 
       case 'list_threads': {
         const threads = this.manager.getKnownThreads();
         return {
-          threads: threads.map((t) => {
-            const topFrame = t.call_stack?.[0];
-            const loc = topFrame?.location;
-            return {
-              thread_id: t.id,
-              status: t.status,
-              current: t.id === this.currentThreadId,
-              location: loc
-                ? {
-                    file: this.sourceMapper.toLocalPath(loc.script_path) ?? null,
-                    line: loc.line_number,
-                    function_name: loc.function_name,
-                    script_path: loc.script_path,
-                  }
-                : null,
-            };
-          }),
+          threads: threads.map((t) => ({
+            thread_id: t.id,
+            status: t.status,
+            current: t.id === this.currentThreadId,
+            location: projectThreadLocation(t, this.sourceMapper),
+          })),
         };
       }
 
@@ -237,31 +191,23 @@ export class DebugRpc {
         }));
 
         const result = await this.manager.setBreakpoints(inputs);
-        return {
-          breakpoints: result.map((bp) => ({
-            id: bp.id,
-            file: this.sourceMapper.toLocalPath(bp.script_path) ?? null,
-            line: bp.line_number,
-            script_path: bp.script_path,
-            condition: bp.condition,
-          })),
-        };
+        return {breakpoints: result.map((bp) => projectBreakpoint(bp, this.sourceMapper))};
       }
 
       case 'step_into': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         await this.manager.stepInto(threadId);
         return {thread_id: threadId, action: 'step_into'};
       }
 
       case 'step_out': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         await this.manager.stepOut(threadId);
         return {thread_id: threadId, action: 'step_out'};
       }
 
       case 'step_over': {
-        const threadId = (args.thread_id as number) ?? this.getThread();
+        const threadId = this.resolveThreadId(args);
         await this.manager.stepOver(threadId);
         return {thread_id: threadId, action: 'step_over'};
       }
@@ -295,16 +241,12 @@ export class DebugRpc {
     }
   }
 
+  /** Resolve a thread_id arg, falling back to the currently selected thread. */
+  private resolveThreadId(args: Record<string, unknown>): number {
+    return (args.thread_id as number) ?? this.getThread();
+  }
+
   private sendResponse(response: RpcResponse): void {
     this.output.write(JSON.stringify(response) + '\n');
   }
 }
-
-function isPrimitive(type: string): boolean {
-  return ['boolean', 'Boolean', 'null', 'number', 'Number', 'string', 'String', 'undefined'].includes(type);
-}
-
-function truncateValue(value: string): string {
-  if (value.length <= MAX_VALUE_LENGTH) return value;
-  return value.slice(0, MAX_VALUE_LENGTH) + '...';
-}

packages/b2c-dx-mcp/src/server-context.ts

@@ -6,6 +6,27 @@
 
 import {DebugSessionRegistry} from './tools/diagnostics/session-registry.js';
 
+/**
+ * Server-scoped persistent state that lives for the lifetime of the MCP
+ * server process. Holds registries for stateful resources (debug sessions,
+ * future log watches) that need to span multiple tool invocations.
+ *
+ * ## Multi-agent / shared-state caveats
+ *
+ * One `ServerContext` is created per MCP server process. With the default
+ * stdio transport, each MCP client connection spawns its own server
+ * subprocess, so this state is naturally isolated per client/agent.
+ *
+ * If this server is ever wired up to a shared transport (e.g. HTTP with
+ * multiple connected clients), `ServerContext` state would be shared
+ * across all connected clients. Sub-agents that run within the same MCP
+ * client would also share the same context. Tools that mutate registries
+ * (like the debug tools) should not assume single-tenant access.
+ *
+ * The debug registry already handles concurrent sessions via session IDs
+ * and host:client_id pairs, so multi-agent use is functional but agents
+ * may see each other's sessions via `debug_list_sessions`.
+ */
 export class ServerContext {
   readonly debugSessions: DebugSessionRegistry;