@salesforce/b2c-dx-mcp 1.1.3 → 1.2.0

package/dist/tools/diagnostics/log-watch-registry.js

@@ -0,0 +1,249 @@
+/*
+ * 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
+/** Maximum number of buffered entries before oldest are evicted. */
+export const DEFAULT_BUFFER_CAP = 5000;
+/**
+ * Maximum cumulative bytes buffered before oldest entries are evicted.
+ * Guards against a small number of pathologically large entries (e.g. multi-MB
+ * stack traces) blowing past the count cap's intended memory bound.
+ */
+export const DEFAULT_BUFFER_BYTES_CAP = 50 * 1024 * 1024; // 50 MB
+/** Maximum number of buffered errors before oldest are evicted. */
+const ERROR_CAP = 25;
+/** Maximum number of buffered rotation events before oldest are evicted. */
+const ROTATION_CAP = 100;
+/** Approximate in-memory byte cost of a buffered entry. */
+function entryBytes(entry) {
+    return (entry.raw?.length ?? 0) + (entry.message?.length ?? 0);
+}
+export class LogWatchRegistry {
+    cleanupTimer;
+    watches = new Map();
+    constructor() {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupIdleWatches().catch(() => { });
+        }, CLEANUP_INTERVAL_MS);
+        this.cleanupTimer.unref();
+    }
+    /**
+     * Append a log entry to a watch buffer. Evicts oldest if over cap.
+     * Resolves any pending poll waiters.
+     */
+    appendEntry(watchId, entry) {
+        const w = this.watches.get(watchId);
+        if (!w || w.stopped)
+            return;
+        w.buffer.push(entry);
+        w.bufferBytes += entryBytes(entry);
+        w.totalEntriesSeen += 1;
+        // Evict oldest entries until under BOTH the count cap and the byte cap.
+        // The byte cap guards against a few pathologically large entries (e.g.
+        // multi-MB stack traces) exceeding the intended memory bound. Always keep
+        // at least one entry so a single oversized entry is still deliverable.
+        while (w.buffer.length > 1 && (w.buffer.length > w.bufferCap || w.bufferBytes > w.bufferBytesCap)) {
+            const dropped = w.buffer.shift();
+            w.bufferBytes -= entryBytes(dropped);
+            w.droppedEntries += 1;
+        }
+        w.lastActivityAt = Date.now();
+        this.flushWaiters(w);
+    }
+    appendError(watchId, err) {
+        const w = this.watches.get(watchId);
+        if (!w || w.stopped)
+            return;
+        w.errors.push({ message: err.message, at: new Date().toISOString() });
+        if (w.errors.length > ERROR_CAP) {
+            w.errors.splice(0, w.errors.length - ERROR_CAP);
+        }
+        w.lastActivityAt = Date.now();
+    }
+    /**
+     * Append a discovered file (deduped by name).
+     */
+    appendFileDiscovered(watchId, file) {
+        const w = this.watches.get(watchId);
+        if (!w || w.stopped)
+            return;
+        if (!w.filesDiscovered.some((f) => f.name === file.name)) {
+            w.filesDiscovered.push(file);
+            // Queue for the next poll drain so each newly-discovered file is reported
+            // exactly once, while filesDiscovered keeps the cumulative view for list.
+            w.pendingFilesDiscovered.push(file);
+        }
+        w.lastActivityAt = Date.now();
+    }
+    appendRotation(watchId, file) {
+        const w = this.watches.get(watchId);
+        if (!w || w.stopped)
+            return;
+        w.rotations.push(file);
+        if (w.rotations.length > ROTATION_CAP) {
+            w.rotations.splice(0, w.rotations.length - ROTATION_CAP);
+        }
+        w.lastActivityAt = Date.now();
+        this.flushWaiters(w);
+    }
+    async destroyAll() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        const promises = [...this.watches.keys()].map((id) => this.destroyWatch(id));
+        await Promise.allSettled(promises);
+    }
+    async destroyWatch(watchId) {
+        const w = this.watches.get(watchId);
+        if (!w)
+            return;
+        w.stopped = true;
+        // Resolve any in-flight waiters so callers don't hang
+        for (const waiter of w.pollWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve();
+        }
+        w.pollWaiters.length = 0;
+        try {
+            await w.stop();
+        }
+        catch {
+            // Best-effort
+        }
+        try {
+            await w.done;
+        }
+        catch {
+            // Tail may reject if it was in the middle of polling; ignore.
+        }
+        this.watches.delete(watchId);
+    }
+    /**
+     * Drain buffered entries (up to maxEntries) and any rotation/error events
+     * from the watch. Removes drained items from the underlying buffers.
+     */
+    drain(watchId, maxEntries) {
+        const w = this.getWatchOrThrow(watchId);
+        const entries = w.buffer.splice(0, maxEntries);
+        for (const e of entries) {
+            w.bufferBytes -= entryBytes(e);
+        }
+        if (w.bufferBytes < 0 || w.buffer.length === 0)
+            w.bufferBytes = 0;
+        const truncated = w.buffer.length > 0;
+        const rotations = w.rotations.splice(0);
+        const errors = w.errors.splice(0);
+        // Only files discovered since the last poll — drained like rotations/errors.
+        const filesDiscovered = w.pendingFilesDiscovered.splice(0);
+        w.lastActivityAt = Date.now();
+        return { entries, errors, filesDiscovered, rotations, truncated };
+    }
+    findByHostname(hostname) {
+        for (const w of this.watches.values()) {
+            if (w.hostname === hostname)
+                return w;
+        }
+        return undefined;
+    }
+    getWatch(watchId) {
+        return this.watches.get(watchId);
+    }
+    getWatchOrThrow(watchId) {
+        const w = this.watches.get(watchId);
+        if (!w) {
+            throw new Error(`No log watch found with id "${watchId}". Use logs_watch_list to see active watches.`);
+        }
+        w.lastActivityAt = Date.now();
+        return w;
+    }
+    listWatches() {
+        return [...this.watches.values()];
+    }
+    registerWatch(opts) {
+        const { hostname, prefixes, tailResult, bufferCap = DEFAULT_BUFFER_CAP, bufferBytesCap = DEFAULT_BUFFER_BYTES_CAP, } = opts;
+        const existing = this.findByHostname(hostname);
+        if (existing) {
+            throw new Error(`A log watch already exists for ${hostname} (watch_id: "${existing.watchId}"). ` +
+                `Stop it with logs_watch_stop first, or poll the existing watch.`);
+        }
+        const watchId = randomUUID();
+        const now = Date.now();
+        const entry = {
+            buffer: [],
+            bufferBytes: 0,
+            bufferBytesCap,
+            bufferCap,
+            createdAt: now,
+            done: tailResult.done,
+            droppedEntries: 0,
+            errors: [],
+            filesDiscovered: [],
+            hostname,
+            lastActivityAt: now,
+            pendingFilesDiscovered: [],
+            pollWaiters: [],
+            prefixes,
+            rotations: [],
+            stop: tailResult.stop,
+            stopped: false,
+            totalEntriesSeen: 0,
+            watchId,
+        };
+        this.watches.set(watchId, entry);
+        return entry;
+    }
+    /**
+     * Wait until at least one entry is buffered (or rotation/error event), or until
+     * timeout elapses. Returns immediately if the buffer is non-empty.
+     */
+    async waitForActivity(watchId, timeoutMs) {
+        const w = this.getWatchOrThrow(watchId);
+        if (w.buffer.length > 0 || w.rotations.length > 0 || w.errors.length > 0 || w.stopped) {
+            return;
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                const idx = w.pollWaiters.findIndex((waiter) => waiter.timer === timer);
+                if (idx !== -1)
+                    w.pollWaiters.splice(idx, 1);
+                resolve();
+            }, timeoutMs);
+            w.pollWaiters.push({ resolve: () => resolve(), timer });
+        });
+    }
+    async cleanupIdleWatches() {
+        const logger = getLogger();
+        const now = Date.now();
+        const idle = [...this.watches.entries()].filter(([, w]) => now - w.lastActivityAt > IDLE_TTL_MS);
+        await Promise.allSettled(idle.map(([id, w]) => {
+            logger.info({ watchId: id, hostname: w.hostname }, 'Cleaning up idle log watch');
+            return this.destroyWatch(id);
+        }));
+    }
+    flushWaiters(w) {
+        if (w.pollWaiters.length === 0)
+            return;
+        const waiters = w.pollWaiters.splice(0);
+        for (const waiter of waiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve();
+        }
+    }
+}
+export function getLogWatchRegistry(context) {
+    const registry = context.serverContext?.logWatches;
+    if (!registry) {
+        throw new Error('Log watch registry not available');
+    }
+    return registry;
+}
+export function getLogWatchEntry(context, watchId) {
+    return getLogWatchRegistry(context).getWatchOrThrow(watchId);
+}
+//# sourceMappingURL=log-watch-registry.js.map

package/dist/tools/diagnostics/logs-get-recent.d.ts

@@ -0,0 +1,9 @@
+import { type GetRecentLogsOptions, type LogEntry } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export interface LogsGetRecentInjections {
+    getRecentLogs?: (instance: B2CInstance, options?: GetRecentLogsOptions) => Promise<LogEntry[]>;
+}
+export declare function createLogsGetRecentTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: LogsGetRecentInjections): McpTool;

package/dist/tools/diagnostics/logs-get-recent.js

@@ -0,0 +1,68 @@
+/*
+ * 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 { filterByLevel, filterBySearch, filterBySince, getRecentLogs, parseSinceTime, } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+const DEFAULT_PREFIXES = ['error', 'customerror'];
+const DEFAULT_COUNT = 50;
+export function createLogsGetRecentTool(loadServices, serverContext, injections) {
+    const getRecentLogsFn = injections?.getRecentLogs ?? getRecentLogs;
+    return createToolAdapter({
+        name: 'logs_get_recent',
+        description: 'Fetch recent log entries from the configured B2C Commerce instance in a single request/response. ' +
+            'Best for quick lookups of the most recent errors. For monitoring across an action you trigger, ' +
+            'use logs_watch_start + logs_watch_poll instead so entries are not missed between calls. ' +
+            'Filters (since, level, search) are applied client-side after fetching.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        requiresInstance: true,
+        inputSchema: {
+            prefixes: z
+                .array(z.string())
+                .optional()
+                .describe('Log prefixes to read. Defaults to ["error", "customerror"].'),
+            count: z.number().int().positive().optional().describe('Maximum number of entries to return. Defaults to 50.'),
+            since: z
+                .string()
+                .optional()
+                .describe('Only entries after this time. Accepts relative ("5m", "1h", "2d") or ISO 8601.'),
+            level: z
+                .array(z.string())
+                .optional()
+                .describe('Filter by log level (ERROR, WARN, INFO, DEBUG, FATAL, TRACE). Case-insensitive.'),
+            search: z
+                .string()
+                .optional()
+                .describe('Case-insensitive substring filter applied to entry message and raw text.'),
+        },
+        async execute(args, context) {
+            const prefixes = args.prefixes ?? DEFAULT_PREFIXES;
+            const count = args.count ?? DEFAULT_COUNT;
+            let sinceDate;
+            if (args.since) {
+                sinceDate = parseSinceTime(args.since);
+            }
+            const needsClientFilter = Boolean(sinceDate || args.level?.length || args.search);
+            const fetchCount = needsClientFilter ? Math.max(count * 5, 500) : count;
+            let entries = await getRecentLogsFn(context.b2cInstance, {
+                prefixes,
+                maxEntries: fetchCount,
+            });
+            if (sinceDate) {
+                entries = filterBySince(entries, sinceDate);
+            }
+            if (args.level && args.level.length > 0) {
+                entries = filterByLevel(entries, args.level);
+            }
+            if (args.search) {
+                entries = filterBySearch(entries, args.search);
+            }
+            entries = entries.slice(0, count);
+            return { count: entries.length, entries };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-get-recent.js.map

package/dist/tools/diagnostics/logs-list-files.d.ts

@@ -0,0 +1,9 @@
+import { type ListLogsOptions, type LogFile } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export interface LogsListFilesInjections {
+    listLogFiles?: (instance: B2CInstance, options?: ListLogsOptions) => Promise<LogFile[]>;
+}
+export declare function createLogsListFilesTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: LogsListFilesInjections): McpTool;

package/dist/tools/diagnostics/logs-list-files.js

@@ -0,0 +1,36 @@
+/*
+ * 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 { listLogFiles } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+export function createLogsListFilesTool(loadServices, serverContext, injections) {
+    const listLogFilesFn = injections?.listLogFiles ?? listLogFiles;
+    return createToolAdapter({
+        name: 'logs_list_files',
+        description: 'List log files on the configured B2C Commerce instance via WebDAV. ' +
+            'Use this to discover what log prefixes are active (error, customerror, debug, jobs, ...) before fetching entries with logs_get_recent or starting a watch.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        requiresInstance: true,
+        inputSchema: {
+            prefixes: z
+                .array(z.string())
+                .optional()
+                .describe('Filter by log prefixes (e.g., ["error", "customerror"]). Returns all when omitted.'),
+            sort_by: z.enum(['date', 'name', 'size']).optional().describe('Sort field. Defaults to "date".'),
+            sort_order: z.enum(['asc', 'desc']).optional().describe('Sort order. Defaults to "desc".'),
+        },
+        async execute(args, context) {
+            const files = await listLogFilesFn(context.b2cInstance, {
+                prefixes: args.prefixes,
+                sortBy: args.sort_by ?? 'date',
+                sortOrder: args.sort_order ?? 'desc',
+            });
+            return { count: files.length, files };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-list-files.js.map

package/dist/tools/diagnostics/logs-watch-list.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 createLogsWatchListTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/logs-watch-list.js

@@ -0,0 +1,36 @@
+/*
+ * 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 { getLogWatchRegistry } from './log-watch-registry.js';
+export function createLogsWatchListTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'logs_watch_list',
+        description: 'List all active log watches with their status. Use this to find an orphaned watch_id (e.g., after a ' +
+            'crashed agent run) so you can resume polling or stop it.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        inputSchema: {},
+        async execute(_args, context) {
+            const registry = getLogWatchRegistry(context);
+            const entries = registry.listWatches();
+            return {
+                watches: entries.map((w) => ({
+                    buffered_entries: w.buffer.length,
+                    created_at: new Date(w.createdAt).toISOString(),
+                    dropped_entries: w.droppedEntries,
+                    files_discovered: w.filesDiscovered,
+                    hostname: w.hostname,
+                    last_activity_at: new Date(w.lastActivityAt).toISOString(),
+                    prefixes: w.prefixes,
+                    stopped: w.stopped,
+                    total_entries_seen: w.totalEntriesSeen,
+                    watch_id: w.watchId,
+                })),
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-watch-list.js.map

package/dist/tools/diagnostics/logs-watch-poll.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 createLogsWatchPollTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/logs-watch-poll.js

@@ -0,0 +1,63 @@
+/*
+ * 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 { getLogWatchRegistry } from './log-watch-registry.js';
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_ENTRIES = 200;
+export function createLogsWatchPollTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'logs_watch_poll',
+        description: 'Drain buffered entries from a log watch. If the buffer is empty, blocks up to timeout_ms waiting for ' +
+            'new entries. Returns immediately if entries are already buffered. Set truncated=true if there are more ' +
+            'entries beyond max_entries — call again to get the rest.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        inputSchema: {
+            watch_id: z.string().describe('Watch id from logs_watch_start.'),
+            timeout_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Max time to block waiting for new entries when buffer is empty. Defaults to 5000ms.'),
+            max_entries: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum entries to return per call. Defaults to 200.'),
+        },
+        async execute(args, context) {
+            const registry = getLogWatchRegistry(context);
+            const watch = registry.getWatchOrThrow(args.watch_id);
+            const timeoutMs = args.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+            const maxEntries = args.max_entries ?? DEFAULT_MAX_ENTRIES;
+            if (watch.buffer.length === 0 &&
+                watch.rotations.length === 0 &&
+                watch.errors.length === 0 &&
+                !watch.stopped &&
+                timeoutMs > 0) {
+                await registry.waitForActivity(args.watch_id, timeoutMs);
+            }
+            const drained = registry.drain(args.watch_id, maxEntries);
+            const droppedSnapshot = watch.droppedEntries;
+            watch.droppedEntries = 0;
+            return {
+                buffered_remaining: watch.buffer.length,
+                dropped_entries: droppedSnapshot,
+                entries: drained.entries,
+                errors: drained.errors,
+                files_discovered: drained.filesDiscovered,
+                files_rotated: drained.rotations,
+                stopped: watch.stopped,
+                truncated: drained.truncated,
+                watch_id: args.watch_id,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-watch-poll.js.map

package/dist/tools/diagnostics/logs-watch-start.d.ts

@@ -0,0 +1,9 @@
+import { type TailLogsOptions, type TailLogsResult } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export interface LogsWatchStartInjections {
+    tailLogs?: (instance: B2CInstance, options?: TailLogsOptions) => Promise<TailLogsResult>;
+}
+export declare function createLogsWatchStartTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: LogsWatchStartInjections): McpTool;

package/dist/tools/diagnostics/logs-watch-start.js

@@ -0,0 +1,117 @@
+/*
+ * 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 { matchesLevel, matchesSearch, tailLogs, } from '@salesforce/b2c-tooling-sdk/operations/logs';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getLogWatchRegistry } from './log-watch-registry.js';
+const DEFAULT_PREFIXES = ['error', 'customerror'];
+export function createLogsWatchStartTool(loadServices, serverContext, injections) {
+    const tailLogsFn = injections?.tailLogs ?? tailLogs;
+    return createToolAdapter({
+        name: 'logs_watch_start',
+        description: 'Start a background log watch on the configured B2C Commerce instance. Returns a watch_id immediately. ' +
+            'Recommended workflow: call logs_watch_start BEFORE triggering the action that should produce logs ' +
+            '(e.g., a storefront request, a job, a debug session). Then call logs_watch_poll to drain buffered ' +
+            'entries (it blocks up to timeout_ms). Always call logs_watch_stop when done. ' +
+            'Only one active watch per hostname at a time — use logs_watch_list to find an existing one.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        requiresInstance: true,
+        inputSchema: {
+            prefixes: z
+                .array(z.string())
+                .optional()
+                .describe('Log prefixes to watch. Defaults to ["error", "customerror"].'),
+            last_entries: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Number of pre-existing entries per file to emit on startup. Defaults to 0 so a fresh ' +
+                'watch only captures NEW entries (matches the recommended "start before triggering" workflow). ' +
+                'Set >0 to include recent context.'),
+            poll_interval_ms: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('How often the underlying tail polls the WebDAV server. Defaults to 3000ms.'),
+            level: z
+                .array(z.string())
+                .optional()
+                .describe('Server-side filter by log level. Entries not matching are dropped before buffering.'),
+            search: z.string().optional().describe('Case-insensitive substring filter applied as entries arrive.'),
+        },
+        async execute(args, context) {
+            const registry = getLogWatchRegistry(context);
+            const prefixes = args.prefixes ?? DEFAULT_PREFIXES;
+            const hostname = context.b2cInstance.config.hostname;
+            // Reserve the watchId on the registry by tracking the hostname check first
+            const existing = registry.findByHostname(hostname);
+            if (existing) {
+                throw new Error(`A log watch already exists for ${hostname} (watch_id: "${existing.watchId}"). ` +
+                    `Stop it with logs_watch_stop first, or poll the existing watch.`);
+            }
+            const levelFilter = args.level;
+            const searchFilter = args.search;
+            // We need the watchId before tailLogs starts emitting, but we can only mint
+            // the id after registerWatch (which itself needs the tailResult). Use a holder
+            // so the callbacks below close over a mutable slot that we fill in after register.
+            const ref = {};
+            const tailResult = await tailLogsFn(context.b2cInstance, {
+                prefixes,
+                pollInterval: args.poll_interval_ms ?? 3000,
+                lastEntries: args.last_entries ?? 0,
+                onEntry(entry) {
+                    if (!ref.id)
+                        return;
+                    if (levelFilter && levelFilter.length > 0 && !matchesLevel(entry, levelFilter)) {
+                        return;
+                    }
+                    if (searchFilter && !matchesSearch(entry, searchFilter)) {
+                        return;
+                    }
+                    registry.appendEntry(ref.id, entry);
+                },
+                onFileDiscovered(file) {
+                    if (!ref.id)
+                        return;
+                    registry.appendFileDiscovered(ref.id, file);
+                },
+                onFileRotated(file) {
+                    if (!ref.id)
+                        return;
+                    registry.appendRotation(ref.id, file);
+                },
+                onError(err) {
+                    if (!ref.id)
+                        return;
+                    registry.appendError(ref.id, err);
+                },
+            });
+            // registerWatch re-checks the hostname and throws on a duplicate. If two
+            // logs_watch_start calls race past the findByHostname check above, the
+            // loser's tailLogs poll is already running in the background — stop it so
+            // it isn't orphaned (it would otherwise poll WebDAV until process exit).
+            let entry;
+            try {
+                entry = registry.registerWatch({ hostname, prefixes, tailResult });
+            }
+            catch (error) {
+                await tailResult.stop().catch(() => { });
+                throw error;
+            }
+            ref.id = entry.watchId;
+            return {
+                hostname,
+                prefixes,
+                started_at: new Date(entry.createdAt).toISOString(),
+                watch_id: entry.watchId,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-watch-start.js.map

package/dist/tools/diagnostics/logs-watch-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 createLogsWatchStopTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/logs-watch-stop.js

@@ -0,0 +1,36 @@
+/*
+ * 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 { getLogWatchRegistry } from './log-watch-registry.js';
+export function createLogsWatchStopTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'logs_watch_stop',
+        description: 'Stop a log watch and release its resources. Idempotent on already-stopped watches (returns 200 with stopped_at). ' +
+            'Always pair with logs_watch_start so polling state does not accumulate on the server.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        inputSchema: {
+            watch_id: z.string().describe('Watch id from logs_watch_start.'),
+        },
+        async execute(args, context) {
+            const registry = getLogWatchRegistry(context);
+            // Idempotent: a watch that was already stopped (and removed) returns a
+            // success response rather than throwing, so retry/cleanup paths are safe.
+            const watch = registry.getWatch(args.watch_id);
+            const totalSeen = watch?.totalEntriesSeen ?? 0;
+            if (watch) {
+                await registry.destroyWatch(args.watch_id);
+            }
+            return {
+                stopped_at: new Date().toISOString(),
+                total_entries_seen: totalSeen,
+                watch_id: args.watch_id,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=logs-watch-stop.js.map

package/dist/tools/docs/docs-list.d.ts

@@ -0,0 +1,3 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+export declare function createDocsListTool(loadServices: () => Promise<Services> | Services): McpTool;