@salesforce/b2c-dx-mcp 1.0.13 → 1.1.0

package/dist/tools/diagnostics/debug-get-variables.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { projectVariable } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getSessionEntry } from './session-registry.js';
+export function createDebugGetVariablesTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_get_variables',
+        description: 'Get variables for a stack frame in a halted thread. ' +
+            'Defaults to top-frame locals. Use scope to filter (local/closure/global) or object_path to drill into nested objects.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            thread_id: z.number().int().describe('Thread ID from debug_wait_for_stop or debug_list_sessions.'),
+            frame_index: z.number().int().min(0).optional().describe('Stack frame index (0 = top frame). Defaults to 0.'),
+            scope: z
+                .enum(['local', 'closure', 'global'])
+                .optional()
+                .describe('Filter variables by scope. If omitted, returns all scopes.'),
+            object_path: z
+                .string()
+                .optional()
+                .describe('Dot-delimited path to drill into an object (e.g. "request.httpParameters"). Returns child members.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const frameIndex = args.frame_index ?? 0;
+            if (args.object_path) {
+                const result = await entry.manager.client.getMembers(args.thread_id, frameIndex, args.object_path);
+                return { variables: result.object_members.map((m) => projectVariable(m, { includeScope: false })) };
+            }
+            const result = await entry.manager.client.getVariables(args.thread_id, frameIndex);
+            const members = args.scope
+                ? result.object_members.filter((m) => m.scope === args.scope)
+                : result.object_members;
+            return { variables: members.map((m) => projectVariable(m)) };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-get-variables.js.map

package/dist/tools/diagnostics/debug-list-sessions.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDebugListSessionsTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-list-sessions.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { projectBreakpoint } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getRegistry } from './session-registry.js';
+export function createDebugListSessionsTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_list_sessions',
+        description: 'List active script debugger sessions with their breakpoints and any halted threads. ' +
+            'Use this to discover orphaned sessions, check whether breakpoints are armed, and poll for halted threads in the non-blocking debug workflow.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {},
+        async execute(_args, context) {
+            const registry = getRegistry(context);
+            const entries = registry.listSessions();
+            return {
+                sessions: entries.map((entry) => ({
+                    session_id: entry.sessionId,
+                    hostname: entry.hostname,
+                    client_id: entry.clientId,
+                    halted_threads: entry.manager
+                        .getKnownThreads()
+                        .filter((t) => t.status === 'halted')
+                        .map((t) => t.id),
+                    breakpoints: entry.breakpoints.map((bp) => projectBreakpoint(bp, entry.sourceMapper)),
+                    created_at: new Date(entry.createdAt).toISOString(),
+                    last_activity_at: new Date(entry.lastActivityAt).toISOString(),
+                })),
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-list-sessions.js.map

package/dist/tools/diagnostics/debug-set-breakpoints.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDebugSetBreakpointsTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-set-breakpoints.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { projectBreakpoint, resolveBreakpointPath, } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getSessionEntry } from './session-registry.js';
+export function createDebugSetBreakpointsTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_set_breakpoints',
+        description: 'Set breakpoints in a debug session. Replaces all previously set breakpoints. ' +
+            'Accepts local file paths (mapped to server paths via cartridge discovery), cartridge-prefixed paths, or server paths starting with /. ' +
+            'Check the "verified" field and "warnings" — unmapped paths are flagged.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            breakpoints: z
+                .array(z.object({
+                file: z
+                    .string()
+                    .describe('Local file path or server script path (e.g. /app_storefront/cartridge/controllers/Cart.js).'),
+                line: z.number().int().positive().describe('Line number for the breakpoint.'),
+                condition: z
+                    .string()
+                    .optional()
+                    .describe('Optional conditional expression. Breakpoint only triggers when this evaluates to true.'),
+            }))
+                .describe('Array of breakpoints to set. Replaces all existing breakpoints.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const warnings = [];
+            const bpInputs = args.breakpoints.map((bp) => {
+                const scriptPath = resolveBreakpointPath(bp.file, entry.sourceMapper, entry.cartridges);
+                if (!entry.sourceMapper.toLocalPath(scriptPath)) {
+                    warnings.push(`"${bp.file}" resolved to server path "${scriptPath}" but could not be mapped back to a local file. ` +
+                        `Verify this path exists on the instance.`);
+                }
+                return { script_path: scriptPath, line_number: bp.line, condition: bp.condition };
+            });
+            const result = await entry.manager.setBreakpoints(bpInputs);
+            entry.breakpoints = result;
+            return {
+                breakpoints: result.map((bp) => ({
+                    ...projectBreakpoint(bp, entry.sourceMapper),
+                    verified: entry.sourceMapper.toLocalPath(bp.script_path) !== undefined,
+                })),
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-set-breakpoints.js.map

package/dist/tools/diagnostics/debug-start-session.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDebugStartSessionTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-start-session.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { DebugSessionManager, createSourceMapper, } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { findCartridges } from '@salesforce/b2c-tooling-sdk/operations/code';
+import { getRegistry } from './session-registry.js';
+export function createDebugStartSessionTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_start_session',
+        description: 'Start a script debugger session on a B2C Commerce instance to debug SFRA controllers, custom API scripts, hooks, jobs, or any server-side script. ' +
+            'Returns a session_id for use with other debug tools, plus discovered cartridge mappings. ' +
+            'WARNING: Debug sessions halt remote request threads on the instance. Always call debug_end_session when finished. ' +
+            'Requires Basic auth credentials (username/password) and the script debugger enabled in Business Manager.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            cartridge_directory: z
+                .string()
+                .optional()
+                .describe('Path to directory containing cartridges. Defaults to project directory.'),
+            client_id: z
+                .string()
+                .optional()
+                .describe('Client ID for the debugger API. Defaults to "b2c-cli". Use a different ID to run concurrent sessions on the same host.'),
+        },
+        async execute(args, context) {
+            const registry = getRegistry(context);
+            const credentials = context.services.getBasicAuthCredentials();
+            if (!credentials) {
+                throw new Error('Basic auth credentials (hostname, username, password) are required for the script debugger. ' +
+                    'Set via SFCC_SERVER/SFCC_USERNAME/SFCC_PASSWORD env vars, or configure in dw.json.');
+            }
+            const { hostname, username, password } = credentials;
+            const clientId = args.client_id ?? 'b2c-cli';
+            const cartridgeDir = context.services.resolveWithProjectDirectory(args.cartridge_directory);
+            const cartridges = findCartridges(cartridgeDir);
+            const warnings = [];
+            if (cartridges.length === 0) {
+                warnings.push(`No cartridges found in ${cartridgeDir}. Breakpoints will use server paths only.`);
+            }
+            const sourceMapper = createSourceMapper(cartridges);
+            const callbacks = {
+                onThreadStopped(thread) {
+                    const entry = registry.findByHostAndClientId(hostname, clientId);
+                    if (!entry)
+                        return;
+                    while (entry.haltWaiters.length > 0) {
+                        const waiter = entry.haltWaiters.shift();
+                        clearTimeout(waiter.timer);
+                        waiter.resolve(thread);
+                    }
+                },
+            };
+            const manager = new DebugSessionManager({ hostname, username, password, clientId, cartridgeRoots: cartridges }, callbacks);
+            await manager.connect();
+            const entry = registry.registerSession({ hostname, clientId, manager, sourceMapper, cartridges });
+            const cartridgeMappings = {};
+            for (const c of cartridges)
+                cartridgeMappings[c.name] = c.src;
+            return {
+                session_id: entry.sessionId,
+                hostname,
+                cartridges: cartridges.map((c) => c.name),
+                cartridge_mappings: cartridgeMappings,
+                warnings,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-start-session.js.map

package/dist/tools/diagnostics/debug-step.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDebugStepTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool[];

package/dist/tools/diagnostics/debug-step.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getSessionEntry } from './session-registry.js';
+const STEP_HANDLERS = {
+    step_into: (m, id) => m.stepInto(id),
+    step_out: (m, id) => m.stepOut(id),
+    step_over: (m, id) => m.stepOver(id),
+};
+function createStepTool(action, description, loadServices, serverContext) {
+    return createToolAdapter({
+        name: `debug_${action}`,
+        description: description + ' Follow with debug_wait_for_stop to see where execution landed.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            thread_id: z.number().int().describe('Thread ID of the halted thread to step.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            await STEP_HANDLERS[action](entry.manager, args.thread_id);
+            return { thread_id: args.thread_id, action };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+export function createDebugStepTools(loadServices, serverContext) {
+    return [
+        createStepTool('step_over', 'Step to the next line in the current function.', loadServices, serverContext),
+        createStepTool('step_into', 'Step into the function call on the current line.', loadServices, serverContext),
+        createStepTool('step_out', 'Step out of the current function, returning to the caller.', loadServices, serverContext),
+    ];
+}
+//# sourceMappingURL=debug-step.js.map

package/dist/tools/diagnostics/debug-wait-for-stop.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDebugWaitForStopTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-wait-for-stop.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { projectThreadLocation } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getRegistry, getSessionEntry } from './session-registry.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+export function createDebugWaitForStopTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_wait_for_stop',
+        description: 'Wait for a thread to halt at a breakpoint or step. ' +
+            'Returns immediately if a thread is already halted; otherwise BLOCKS until a halt occurs or the timeout expires. ' +
+            'Preferred non-blocking alternative: after debug_set_breakpoints, trigger the request yourself, then use debug_list_sessions to check halted_threads before calling debug_get_stack/debug_get_variables.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            timeout_ms: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_TIMEOUT_MS)
+                .optional()
+                .describe(`Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS}).`),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const timeout = Math.min(args.timeout_ms ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+            const thread = await getRegistry(context).waitForHalt(entry, timeout);
+            if (!thread)
+                return { halted: false, timed_out: true };
+            const location = projectThreadLocation(thread, entry.sourceMapper);
+            return {
+                halted: true,
+                thread_id: thread.id,
+                location: location ?? undefined,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-wait-for-stop.js.map

package/dist/tools/diagnostics/index.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createDiagnosticsTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool[];

package/dist/tools/diagnostics/index.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { createDebugListSessionsTool } from './debug-list-sessions.js';
+import { createDebugStartSessionTool } from './debug-start-session.js';
+import { createDebugEndSessionTool } from './debug-end-session.js';
+import { createDebugSetBreakpointsTool } from './debug-set-breakpoints.js';
+import { createDebugWaitForStopTool } from './debug-wait-for-stop.js';
+import { createDebugGetStackTool } from './debug-get-stack.js';
+import { createDebugGetVariablesTool } from './debug-get-variables.js';
+import { createDebugEvaluateTool } from './debug-evaluate.js';
+import { createDebugContinueTool } from './debug-continue.js';
+import { createDebugStepTools } from './debug-step.js';
+import { createDebugCaptureAtBreakpointTool } from './debug-capture-at-breakpoint.js';
+export function createDiagnosticsTools(loadServices, serverContext) {
+    return [
+        createDebugListSessionsTool(loadServices, serverContext),
+        createDebugStartSessionTool(loadServices, serverContext),
+        createDebugEndSessionTool(loadServices, serverContext),
+        createDebugSetBreakpointsTool(loadServices, serverContext),
+        createDebugWaitForStopTool(loadServices, serverContext),
+        createDebugGetStackTool(loadServices, serverContext),
+        createDebugGetVariablesTool(loadServices, serverContext),
+        createDebugEvaluateTool(loadServices, serverContext),
+        createDebugContinueTool(loadServices, serverContext),
+        ...createDebugStepTools(loadServices, serverContext),
+        createDebugCaptureAtBreakpointTool(loadServices, serverContext),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/diagnostics/session-registry.d.ts

@@ -0,0 +1,56 @@
+import type { DebugSessionManager, SourceMapper, SdapiBreakpoint, SdapiScriptThread } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import type { CartridgeMapping } from '@salesforce/b2c-tooling-sdk/operations/code';
+import type { ToolExecutionContext } from '../adapter.js';
+export interface HaltWaiter {
+    resolve: (thread: SdapiScriptThread) => void;
+    reject: (error: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+export interface DebugSessionEntry {
+    sessionId: string;
+    hostname: string;
+    clientId: string;
+    manager: DebugSessionManager;
+    sourceMapper: SourceMapper;
+    cartridges: CartridgeMapping[];
+    breakpoints: SdapiBreakpoint[];
+    haltWaiters: HaltWaiter[];
+    createdAt: number;
+    lastActivityAt: number;
+}
+export interface RegisterSessionOptions {
+    hostname: string;
+    clientId: string;
+    manager: DebugSessionManager;
+    sourceMapper: SourceMapper;
+    cartridges: CartridgeMapping[];
+}
+export declare class DebugSessionRegistry {
+    private cleanupTimer;
+    private readonly sessions;
+    constructor();
+    destroyAll(): Promise<void>;
+    destroySession(sessionId: string): Promise<void>;
+    findByHostAndClientId(hostname: string, clientId: string): DebugSessionEntry | undefined;
+    getSession(sessionId: string): DebugSessionEntry | undefined;
+    getSessionOrThrow(sessionId: string): DebugSessionEntry;
+    listSessions(): DebugSessionEntry[];
+    registerSession(opts: RegisterSessionOptions): DebugSessionEntry;
+    /**
+     * Wait for any thread in the session to halt.
+     *
+     * If a thread is already halted in the session's known threads, returns it
+     * immediately. Otherwise registers a halt waiter that resolves when the
+     * `onThreadStopped` callback fires, or returns null on timeout.
+     */
+    waitForHalt(entry: DebugSessionEntry, timeoutMs: number): Promise<null | SdapiScriptThread>;
+    private cleanupIdleSessions;
+}
+/**
+ * Resolve the registry from the tool execution context, throwing a clear
+ * error if it's missing, then look up the session by ID. Used by every
+ * debug tool that takes a session_id.
+ */
+export declare function getSessionEntry(context: ToolExecutionContext, sessionId: string): DebugSessionEntry;
+/** Resolve the registry from the tool context (for tools that don't need a specific session). */
+export declare function getRegistry(context: ToolExecutionContext): DebugSessionRegistry;

package/dist/tools/diagnostics/session-registry.js

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
+const IDLE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+export class DebugSessionRegistry {
+    cleanupTimer;
+    sessions = new Map();
+    constructor() {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupIdleSessions().catch(() => { });
+        }, CLEANUP_INTERVAL_MS);
+        this.cleanupTimer.unref();
+    }
+    async destroyAll() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        const destroyPromises = [...this.sessions.keys()].map((id) => this.destroySession(id));
+        await Promise.allSettled(destroyPromises);
+    }
+    async destroySession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return;
+        for (const waiter of entry.haltWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new Error('Debug session ended'));
+        }
+        entry.haltWaiters.length = 0;
+        try {
+            await entry.manager.disconnect();
+        }
+        catch {
+            // Best-effort disconnect
+        }
+        this.sessions.delete(sessionId);
+    }
+    findByHostAndClientId(hostname, clientId) {
+        for (const entry of this.sessions.values()) {
+            if (entry.hostname === hostname && entry.clientId === clientId) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    getSessionOrThrow(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry) {
+            throw new Error(`No debug session found with id "${sessionId}". Use debug_list_sessions to see active sessions.`);
+        }
+        entry.lastActivityAt = Date.now();
+        return entry;
+    }
+    listSessions() {
+        return [...this.sessions.values()];
+    }
+    registerSession(opts) {
+        const { hostname, clientId, manager, sourceMapper, cartridges } = opts;
+        const existing = this.findByHostAndClientId(hostname, clientId);
+        if (existing) {
+            throw new Error(`A debug session already exists for ${hostname} with client ID "${clientId}" ` +
+                `(session_id: "${existing.sessionId}"). ` +
+                `End it with debug_end_session first, or use a different client_id.`);
+        }
+        const sessionId = randomUUID();
+        const now = Date.now();
+        const entry = {
+            sessionId,
+            hostname,
+            clientId,
+            manager,
+            sourceMapper,
+            cartridges,
+            breakpoints: [],
+            haltWaiters: [],
+            createdAt: now,
+            lastActivityAt: now,
+        };
+        this.sessions.set(sessionId, entry);
+        return entry;
+    }
+    /**
+     * Wait for any thread in the session to halt.
+     *
+     * If a thread is already halted in the session's known threads, returns it
+     * immediately. Otherwise registers a halt waiter that resolves when the
+     * `onThreadStopped` callback fires, or returns null on timeout.
+     */
+    async waitForHalt(entry, timeoutMs) {
+        const halted = entry.manager.getKnownThreads().find((t) => t.status === 'halted');
+        if (halted)
+            return halted;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const idx = entry.haltWaiters.findIndex((w) => w.timer === timer);
+                if (idx !== -1)
+                    entry.haltWaiters.splice(idx, 1);
+                resolve(null);
+            }, timeoutMs);
+            entry.haltWaiters.push({ resolve: (t) => resolve(t), reject, timer });
+        });
+    }
+    async cleanupIdleSessions() {
+        const logger = getLogger();
+        const now = Date.now();
+        const idleSessions = [...this.sessions.entries()].filter(([, entry]) => now - entry.lastActivityAt > IDLE_TTL_MS);
+        await Promise.allSettled(idleSessions.map(([sessionId, entry]) => {
+            logger.info({ sessionId, hostname: entry.hostname }, 'Cleaning up idle debug session');
+            return this.destroySession(sessionId);
+        }));
+    }
+}
+/**
+ * Resolve the registry from the tool execution context, throwing a clear
+ * error if it's missing, then look up the session by ID. Used by every
+ * debug tool that takes a session_id.
+ */
+export function getSessionEntry(context, sessionId) {
+    const registry = context.serverContext?.debugSessions;
+    if (!registry) {
+        throw new Error('Debug session registry not available');
+    }
+    return registry.getSessionOrThrow(sessionId);
+}
+/** Resolve the registry from the tool context (for tools that don't need a specific session). */
+export function getRegistry(context) {
+    const registry = context.serverContext?.debugSessions;
+    if (!registry) {
+        throw new Error('Debug session registry not available');
+    }
+    return registry;
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/tools/index.d.ts

@@ -9,6 +9,7 @@
  */
 export * from './adapter.js';
 export * from './cartridges/index.js';
+export * from './diagnostics/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
 export * from './scapi/index.js';

package/dist/tools/index.js

@@ -16,6 +16,7 @@
 export * from './adapter.js';
 // Toolset exports
 export * from './cartridges/index.js';
+export * from './diagnostics/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
 export * from './scapi/index.js';

package/oclif.manifest.json

@@ -249,6 +249,7 @@
           "multiple": true,
           "options": [
             "client-credentials",
+            "jwt",
             "implicit",
             "basic",
             "api-key"
@@ -274,6 +275,33 @@
           "multiple": false,
           "type": "option"
         },
+        "jwt-cert": {
+          "description": "Path to JWT certificate file (cert.pem) for JWT Bearer authentication",
+          "env": "SFCC_JWT_CERT",
+          "helpGroup": "AUTH",
+          "name": "jwt-cert",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "jwt-key": {
+          "description": "Path to JWT private key file (key.pem) for JWT Bearer authentication",
+          "env": "SFCC_JWT_KEY",
+          "helpGroup": "AUTH",
+          "name": "jwt-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "jwt-passphrase": {
+          "description": "Passphrase for encrypted JWT private key",
+          "env": "SFCC_JWT_PASSPHRASE",
+          "helpGroup": "AUTH",
+          "name": "jwt-passphrase",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "server": {
           "char": "s",
           "description": "B2C instance hostname",
@@ -390,5 +418,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.0.13"
+  "version": "1.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.0.13",
+  "version": "1.1.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,7 +80,7 @@
     "yaml": "2.8.1",
     "postcss": "8.5.6",
     "zod": "3.25.76",
-    "@salesforce/b2c-tooling-sdk": "1.7.0"
+    "@salesforce/b2c-tooling-sdk": "1.9.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",