@vfarcic/dot-ai 0.178.0 → 0.180.0

package/dist/core/generic-session-manager.d.ts

@@ -61,6 +61,11 @@ export declare class GenericSessionManager<T = any> {
     clearAllSessions(): void;
     /**
      * Save session to file
+     *
+     * Note: Uses a custom replacer to convert undefined values to null.
+     * This is critical because JSON.stringify drops undefined values entirely,
+     * which would cause data loss in toolCallsExecuted arrays where tool
+     * outputs may have undefined fields. (PRD #320 Milestone 2.5)
      */
     private saveSession;
 }

package/dist/core/generic-session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic-session-manager.d.ts","sourceRoot":"","sources":["../../src/core/generic-session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,qBAAa,qBAAqB,CAAC,CAAC,GAAG,GAAG;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAE7B;;;OAGG;gBACS,MAAM,EAAE,MAAM;IAW1B;;;OAGG;IACH,aAAa,CAAC,WAAW,GAAE,CAAW,GAAG,cAAc,CAAC,CAAC,CAAC;IAgB1D;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBvD;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAc/E;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAcvE;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAgBzC;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAgBxB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAiBxB;;OAEG;IACH,OAAO,CAAC,WAAW;CAIpB"}
+{"version":3,"file":"generic-session-manager.d.ts","sourceRoot":"","sources":["../../src/core/generic-session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;GAEG;AACH,qBAAa,qBAAqB,CAAC,CAAC,GAAG,GAAG;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAE7B;;;OAGG;gBACS,MAAM,EAAE,MAAM;IAW1B;;;OAGG;IACH,aAAa,CAAC,WAAW,GAAE,CAAW,GAAG,cAAc,CAAC,CAAC,CAAC;IAgB1D;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBvD;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAc/E;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAcvE;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAgBzC;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAgBxB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAiBxB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;CAMpB"}

package/dist/core/generic-session-manager.js

@@ -183,10 +183,17 @@ class GenericSessionManager {
     }
     /**
      * Save session to file
+     *
+     * Note: Uses a custom replacer to convert undefined values to null.
+     * This is critical because JSON.stringify drops undefined values entirely,
+     * which would cause data loss in toolCallsExecuted arrays where tool
+     * outputs may have undefined fields. (PRD #320 Milestone 2.5)
      */
     saveSession(session) {
         const sessionFile = path.join(this.sessionsPath, `${session.sessionId}.json`);
-        fs.writeFileSync(sessionFile, JSON.stringify(session, null, 2), 'utf8');
+        // Convert undefined to null to preserve structure during JSON serialization
+        const replacer = (_key, value) => value === undefined ? null : value;
+        fs.writeFileSync(sessionFile, JSON.stringify(session, replacer, 2), 'utf8');
     }
 }
 exports.GenericSessionManager = GenericSessionManager;

package/dist/core/mermaid-tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Mermaid Validation Tools for AI-Powered Visualization
+ *
+ * Provides Mermaid diagram validation tools for the visualization AI.
+ * Allows AI to validate diagrams before returning them to the user.
+ *
+ * PRD #320: Milestone 2.6 - Mermaid Diagram Validation
+ */
+import { AITool } from './ai-provider.interface';
+/**
+ * Tool: validate_mermaid
+ * Validates Mermaid diagram syntax and returns errors if any
+ */
+export declare const VALIDATE_MERMAID_TOOL: AITool;
+/**
+ * All mermaid tools for visualization
+ */
+export declare const MERMAID_TOOLS: AITool[];
+/**
+ * Execute Mermaid-related tools
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+export declare function executeMermaidTools(toolName: string, input: any): Promise<any>;
+//# sourceMappingURL=mermaid-tools.d.ts.map

package/dist/core/mermaid-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-tools.d.ts","sourceRoot":"","sources":["../../src/core/mermaid-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAWjD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MA0BnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,EAEjC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,GAAG,GACT,OAAO,CAAC,GAAG,CAAC,CAoDd"}

package/dist/core/mermaid-tools.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Mermaid Validation Tools for AI-Powered Visualization
+ *
+ * Provides Mermaid diagram validation tools for the visualization AI.
+ * Allows AI to validate diagrams before returning them to the user.
+ *
+ * PRD #320: Milestone 2.6 - Mermaid Diagram Validation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MERMAID_TOOLS = exports.VALIDATE_MERMAID_TOOL = void 0;
+exports.executeMermaidTools = executeMermaidTools;
+const mermaid_1 = __importDefault(require("mermaid"));
+// Initialize mermaid with strict validation
+mermaid_1.default.initialize({
+    securityLevel: 'strict',
+    startOnLoad: false,
+    // Disable rendering, we only want parsing/validation
+    suppressErrorRendering: true
+});
+/**
+ * Tool: validate_mermaid
+ * Validates Mermaid diagram syntax and returns errors if any
+ */
+exports.VALIDATE_MERMAID_TOOL = {
+    name: 'validate_mermaid',
+    description: `Validates Mermaid diagram syntax. Use this tool to check if a Mermaid diagram has correct syntax BEFORE including it in visualizations.
+
+IMPORTANT: Always validate all Mermaid diagrams before returning them. If validation fails, fix the error and validate again.
+
+Common Mermaid syntax errors to watch for:
+- "classDist" should be "classDef" (class definition)
+- Missing quotes around labels with special characters
+- Invalid node/edge syntax
+- Unbalanced brackets or parentheses
+
+Returns:
+- valid: boolean - true if diagram is valid
+- error: string | null - error message if invalid, null if valid
+- parseError: object | null - detailed parse error info if available`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            diagram: {
+                type: 'string',
+                description: 'The Mermaid diagram code to validate (without the ```mermaid code fence)'
+            }
+        },
+        required: ['diagram']
+    }
+};
+/**
+ * All mermaid tools for visualization
+ */
+exports.MERMAID_TOOLS = [
+    exports.VALIDATE_MERMAID_TOOL
+];
+/**
+ * Execute Mermaid-related tools
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+async function executeMermaidTools(toolName, input) {
+    if (toolName !== 'validate_mermaid') {
+        return {
+            success: false,
+            error: `Unknown mermaid tool: ${toolName}`,
+            message: `Tool '${toolName}' is not a mermaid tool`
+        };
+    }
+    const { diagram } = input;
+    if (!diagram || typeof diagram !== 'string') {
+        return {
+            success: false,
+            valid: false,
+            error: 'Missing or invalid diagram parameter. Provide the Mermaid diagram code as a string.'
+        };
+    }
+    try {
+        // Use mermaid.parse() to validate syntax without rendering
+        // This returns true if valid, or throws an error if invalid
+        await mermaid_1.default.parse(diagram);
+        return {
+            success: true,
+            valid: true,
+            error: null,
+            parseError: null,
+            message: 'Diagram syntax is valid'
+        };
+    }
+    catch (error) {
+        // Extract useful error information
+        const errorMessage = error.message || String(error);
+        // Check if it's a parser error with detailed info
+        const parseError = error.hash ? {
+            text: error.hash.text,
+            token: error.hash.token,
+            line: error.hash.line,
+            loc: error.hash.loc,
+            expected: error.hash.expected
+        } : null;
+        return {
+            success: true, // Tool executed successfully, but diagram is invalid
+            valid: false,
+            error: errorMessage,
+            parseError,
+            message: `Diagram validation failed: ${errorMessage}`
+        };
+    }
+}

package/dist/core/providers/vercel-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vercel-provider.d.ts","sourceRoot":"","sources":["../../../src/core/providers/vercel-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EACL,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,0BAA0B,CAAC;AAiBlC,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,aAAa,CAAM;gBAEf,MAAM,EAAE,gBAAgB;IAWpC,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,eAAe;IAsFvB,eAAe,IAAI,MAAM;IAIzB,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM;IAItB,aAAa,IAAI,OAAO;IAIxB,OAAO,CAAC,iBAAiB;IAyBnB,WAAW,CACf,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAkB,EAC7B,iBAAiB,CAAC,EAAE;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,UAAU,CAAC;IAoJtB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAmW/D"}
+{"version":3,"file":"vercel-provider.d.ts","sourceRoot":"","sources":["../../../src/core/providers/vercel-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EACL,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,0BAA0B,CAAC;AAiBlC,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,aAAa,CAAM;gBAEf,MAAM,EAAE,gBAAgB;IAWpC,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,eAAe;IAsFvB,eAAe,IAAI,MAAM;IAIzB,eAAe,IAAI,MAAM;IAIzB,YAAY,IAAI,MAAM;IAItB,aAAa,IAAI,OAAO;IAIxB,OAAO,CAAC,iBAAiB;IAyBnB,WAAW,CACf,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAkB,EAC7B,iBAAiB,CAAC,EAAE;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,UAAU,CAAC;IAoJtB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAiW/D"}

package/dist/core/providers/vercel-provider.js

@@ -278,6 +278,9 @@ class VercelProvider {
             const operation = config.operation || 'tool-loop';
             // Convert AITool[] to Vercel AI SDK tool format
             const tools = {};
+            // PRD #320: Capture tool calls during execution (not reconstruction from steps)
+            // This ensures toolCallsExecuted has actual data for visualization
+            const toolCallsExecuted = [];
             for (let i = 0; i < config.tools.length; i++) {
                 const aiTool = config.tools[i];
                 const isLastTool = i === config.tools.length - 1;
@@ -285,7 +288,15 @@ class VercelProvider {
                     description: aiTool.description,
                     inputSchema: (0, ai_1.jsonSchema)(aiTool.inputSchema),
                     execute: async (input) => {
-                        return await config.toolExecutor(aiTool.name, input);
+                        // Execute and capture result
+                        const output = await config.toolExecutor(aiTool.name, input);
+                        // Capture for toolCallsExecuted array
+                        toolCallsExecuted.push({
+                            tool: aiTool.name,
+                            input,
+                            output,
+                        });
+                        return output;
                     },
                 });
                 // Add cache control ONLY to last tool for Anthropic (max 4 cache breakpoints)
@@ -448,18 +459,8 @@ class VercelProvider {
                     };
                     debugFiles = this.logDebugIfEnabled(`${operation}-raw`, finalPrompt, rawAiResponse);
                 }
-                // Extract tool call history from steps
-                const toolCallsExecuted = [];
-                for (const step of result.steps || []) {
-                    for (const toolCall of step.toolCalls || []) {
-                        const toolResult = step.toolResults?.find((tr) => tr.toolCallId === toolCall.toolCallId);
-                        toolCallsExecuted.push({
-                            tool: toolCall.toolName,
-                            input: toolCall.args,
-                            output: toolResult?.result,
-                        });
-                    }
-                }
+                // PRD #320: toolCallsExecuted is now captured during execution (see tool wrapper above)
+                // This replaces the old reconstruction from result.steps which lost input/output data
                 // Normalize token metrics across providers
                 // NOTE: Vercel AI SDK had token reporting bugs that were fixed in PR #8945 (merged Sept 26, 2025)
                 // - GitHub Issue #8349: cache tokens only reflected last step, not summed across all steps

package/dist/core/visualization.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared Visualization Utilities (PRD #320)
+ *
+ * Common utilities for visualization support across all MCP tools.
+ * Provides session metadata interfaces, URL generation, and prompt selection.
+ */
+import { VisualizationType } from '../interfaces/rest-api';
+/**
+ * Cached visualization structure stored in sessions
+ * PRD #320: Added toolsUsed for test validation of mermaid validation
+ */
+export interface CachedVisualization {
+    title: string;
+    visualizations: Array<{
+        id: string;
+        label: string;
+        type: VisualizationType;
+        content: any;
+    }>;
+    insights: string[];
+    toolsUsed?: string[];
+    generatedAt: string;
+}
+/**
+ * Base interface for visualization session data
+ * All tools should include these fields for visualization support
+ */
+export interface BaseVisualizationData {
+    /** Tool that created this session: 'query' | 'recommend' | 'remediate' | etc. */
+    toolName: string;
+    /** Optional stage for multi-stage tools (e.g., 'recommend', 'generateManifests') */
+    stage?: string;
+    /** Cached visualization to avoid re-generation */
+    cachedVisualization?: CachedVisualization;
+}
+/**
+ * Supported tool names for visualization
+ */
+export type VisualizationToolName = 'query' | 'recommend' | 'remediate' | 'operate' | 'version' | 'projectSetup';
+/**
+ * Get the prompt file name for visualization
+ * All tools use the unified visualize.md template (PRD #320)
+ *
+ * @param toolName - Name of the tool (unused, kept for API compatibility)
+ * @returns Prompt file name (without .md extension)
+ */
+export declare function getPromptForTool(_toolName: string): string;
+/**
+ * Get visualization URL if WEB_UI_BASE_URL is configured
+ * Feature toggle - only returns URL when env var is set
+ *
+ * @param sessionIds - Single session ID or array of session IDs to include in URL
+ * @returns Visualization URL or undefined if not configured
+ */
+export declare function getVisualizationUrl(sessionIds: string | string[]): string | undefined;
+/**
+ * Extract the session prefix from a session ID
+ * Session IDs are formatted: {prefix}-{timestamp}-{uuid}
+ *
+ * @param sessionId - Full session ID (e.g., 'qry-1704067200000-a1b2c3d4')
+ * @returns Session prefix (e.g., 'qry')
+ */
+export declare function extractPrefixFromSessionId(sessionId: string): string;
+/**
+ * Session prefixes used by each tool
+ * Useful for documentation and validation
+ */
+export declare const TOOL_SESSION_PREFIXES: Record<string, string>;
+/**
+ * Get the tool name from a session prefix
+ * Reverse lookup from prefix to tool name
+ *
+ * @param prefix - Session prefix (e.g., 'qry')
+ * @returns Tool name or undefined if not recognized
+ */
+export declare function getToolNameFromPrefix(prefix: string): string | undefined;
+//# sourceMappingURL=visualization.d.ts.map

package/dist/core/visualization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualization.d.ts","sourceRoot":"","sources":["../../src/core/visualization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,KAAK,CAAC;QACpB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,iBAAiB,CAAC;QACxB,OAAO,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,WAAW,GACX,WAAW,GACX,SAAS,GACT,SAAS,GACT,cAAc,CAAC;AAEnB;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAUrF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOxD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOxE"}

package/dist/core/visualization.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Shared Visualization Utilities (PRD #320)
+ *
+ * Common utilities for visualization support across all MCP tools.
+ * Provides session metadata interfaces, URL generation, and prompt selection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_SESSION_PREFIXES = void 0;
+exports.getPromptForTool = getPromptForTool;
+exports.getVisualizationUrl = getVisualizationUrl;
+exports.extractPrefixFromSessionId = extractPrefixFromSessionId;
+exports.getToolNameFromPrefix = getToolNameFromPrefix;
+/**
+ * Get the prompt file name for visualization
+ * All tools use the unified visualize.md template (PRD #320)
+ *
+ * @param toolName - Name of the tool (unused, kept for API compatibility)
+ * @returns Prompt file name (without .md extension)
+ */
+function getPromptForTool(_toolName) {
+    return 'visualize';
+}
+/**
+ * Get visualization URL if WEB_UI_BASE_URL is configured
+ * Feature toggle - only returns URL when env var is set
+ *
+ * @param sessionIds - Single session ID or array of session IDs to include in URL
+ * @returns Visualization URL or undefined if not configured
+ */
+function getVisualizationUrl(sessionIds) {
+    const baseUrl = process.env.WEB_UI_BASE_URL;
+    if (!baseUrl) {
+        return undefined;
+    }
+    // Remove trailing slash if present, then append /v/{sessionId(s)}
+    const normalizedBaseUrl = baseUrl.replace(/\/$/, '');
+    // Join multiple session IDs with + separator
+    const sessionPath = Array.isArray(sessionIds) ? sessionIds.join('+') : sessionIds;
+    return `${normalizedBaseUrl}/v/${sessionPath}`;
+}
+/**
+ * Extract the session prefix from a session ID
+ * Session IDs are formatted: {prefix}-{timestamp}-{uuid}
+ *
+ * @param sessionId - Full session ID (e.g., 'qry-1704067200000-a1b2c3d4')
+ * @returns Session prefix (e.g., 'qry')
+ */
+function extractPrefixFromSessionId(sessionId) {
+    const parts = sessionId.split('-');
+    // Return first part as prefix, default to 'qry' if invalid
+    return parts[0] || 'qry';
+}
+/**
+ * Session prefixes used by each tool
+ * Useful for documentation and validation
+ */
+exports.TOOL_SESSION_PREFIXES = {
+    query: 'qry',
+    recommend: 'sol', // "solution" - recommend tool provides solutions
+    remediate: 'rem',
+    operate: 'opr',
+    version: 'ver',
+    projectSetup: 'prj',
+};
+/**
+ * Get the tool name from a session prefix
+ * Reverse lookup from prefix to tool name
+ *
+ * @param prefix - Session prefix (e.g., 'qry')
+ * @returns Tool name or undefined if not recognized
+ */
+function getToolNameFromPrefix(prefix) {
+    for (const [tool, toolPrefix] of Object.entries(exports.TOOL_SESSION_PREFIXES)) {
+        if (toolPrefix === prefix) {
+            return tool;
+        }
+    }
+    return undefined;
+}

package/dist/interfaces/rest-api.d.ts

@@ -59,8 +59,22 @@ export interface ToolDiscoveryResponse extends RestApiResponse {
 }
 /**
  * Visualization types supported by the API
+ * PRD #320: Added 'diff' type for before/after comparisons
  */
-export type VisualizationType = 'mermaid' | 'cards' | 'code' | 'table';
+export type VisualizationType = 'mermaid' | 'cards' | 'code' | 'table' | 'diff';
+/**
+ * Diff visualization content (PRD #320)
+ */
+export interface DiffVisualizationContent {
+    before: {
+        language: string;
+        code: string;
+    };
+    after: {
+        language: string;
+        code: string;
+    };
+}
 /**
  * Individual visualization item
  */
@@ -79,15 +93,17 @@ export interface Visualization {
         title: string;
         description?: string;
         tags?: string[];
-    }>;
+    }> | DiffVisualizationContent;
 }
 /**
  * Visualization endpoint response format
+ * PRD #320: Added toolsUsed for test validation of mermaid validation
  */
 export interface VisualizationResponse {
     title: string;
     visualizations: Visualization[];
     insights: string[];
+    toolsUsed?: string[];
 }
 /**
  * REST API router configuration
@@ -144,6 +160,7 @@ export declare class RestApiRouter {
     /**
      * Handle visualization requests (PRD #317)
      * Returns structured visualization data for a query session
+     * PRD #320: Supports ?reload=true to regenerate visualization from current session data
      */
     private handleVisualize;
     /**

package/dist/interfaces/rest-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-api.d.ts","sourceRoot":"","sources":["../../src/interfaces/rest-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAmBtC;;GAEG;AACH,oBAAY,UAAU;IACpB,EAAE,MAAM;IACR,WAAW,MAAM;IACjB,SAAS,MAAM;IACf,kBAAkB,MAAM;IACxB,qBAAqB,MAAM;IAC3B,mBAAmB,MAAM;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,CAAC;IACF,IAAI,CAAC,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,IAAI,CAAC,EAAE;QACL,MAAM,EAAE,GAAG,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,QAAQ,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC9K;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAmB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAa;gBAGjC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAoBrC;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAqHzF;;OAEG;IACH,OAAO,CAAC,YAAY;IA+DpB;;OAEG;YACW,mBAAmB;IA2CjC;;OAEG;YACW,mBAAmB;IAgGjC;;OAEG;YACW,iBAAiB;IA8B/B;;OAEG;YACW,yBAAyB;IAgEvC;;OAEG;YACW,wBAAwB;IA0CtC;;OAEG;YACW,uBAAuB;IAsDrC;;;OAGG;YACW,eAAe;IAuP7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;YACW,gBAAgB;IAK9B;;OAEG;YACW,iBAAiB;IAyB/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,SAAS,IAAI,aAAa;CAG3B"}
+{"version":3,"file":"rest-api.d.ts","sourceRoot":"","sources":["../../src/interfaces/rest-api.ts"],"names":[],"mappings":"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"}