@probelabs/probe 0.6.0-rc224 → 0.6.0-rc226

package/build/agent/mcp/xmlBridge.js

@@ -321,14 +321,17 @@ export function parseHybridXmlToolCall(xmlString, nativeTools = [], mcpBridge =
   // This includes thinking tag removal and attempt_complete recovery logic
   const nativeResult = parseNativeXmlToolWithThinking(xmlString, nativeTools);
   if (nativeResult) {
-    return { ...nativeResult, type: 'native' };
+    const { thinkingContent, ...rest } = nativeResult;
+    return { ...rest, type: 'native', thinkingContent };
   }
 
   // Then try MCP tools if bridge is available
   if (mcpBridge) {
     const mcpResult = parseXmlMcpToolCall(xmlString, mcpBridge.getToolNames());
     if (mcpResult) {
-      return { ...mcpResult, type: 'mcp' };
+      // Extract thinking content for MCP tools as well
+      const { thinkingContent } = processXmlWithThinkingAndRecovery(xmlString, []);
+      return { ...mcpResult, type: 'mcp', thinkingContent };
     }
   }
 
@@ -344,18 +347,18 @@ export function parseHybridXmlToolCall(xmlString, nativeTools = [], mcpBridge =
  */
 function parseNativeXmlToolWithThinking(xmlString, validTools) {
   // Use the shared processing logic
-  const { cleanedXmlString, recoveryResult } = processXmlWithThinkingAndRecovery(xmlString, validTools);
-  
-  // If recovery found an attempt_complete pattern, return it
+  const { cleanedXmlString, recoveryResult, thinkingContent } = processXmlWithThinkingAndRecovery(xmlString, validTools);
+
+  // If recovery found an attempt_complete pattern, return it with thinking content
   if (recoveryResult) {
-    return recoveryResult;
+    return { ...recoveryResult, thinkingContent };
   }
 
   // Use the original parseNativeXmlTool function to parse the cleaned XML string
   for (const toolName of validTools) {
     const result = parseNativeXmlTool(cleanedXmlString, toolName);
     if (result) {
-      return result;
+      return { ...result, thinkingContent };
     }
   }
 

package/build/agent/simpleTelemetry.js

@@ -264,6 +264,204 @@ export class SimpleAppTracer {
     }
   }
 
+  /**
+   * Hash content for deduplication/comparison purposes
+   * @param {string} content - The content to hash
+   * @returns {string} - Hex string hash
+   */
+  hashContent(content) {
+    let hash = 0;
+    const len = Math.min(content.length, 1000);
+    for (let i = 0; i < len; i++) {
+      hash = ((hash << 5) - hash) + content.charCodeAt(i);
+      hash |= 0; // Convert to 32-bit integer
+    }
+    return hash.toString(16);
+  }
+
+  /**
+   * Record a conversation turn (assistant response or tool result)
+   * @param {string} role - The role (assistant, tool_result)
+   * @param {string} content - The turn content
+   * @param {Object} metadata - Additional metadata
+   */
+  recordConversationTurn(role, content, metadata = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent(`conversation.turn.${role}`, {
+      'session.id': this.sessionId,
+      'conversation.role': role,
+      'conversation.content': content.substring(0, 10000),
+      'conversation.content.length': content.length,
+      'conversation.content.hash': this.hashContent(content),
+      ...metadata
+    });
+  }
+
+  /**
+   * Record error events with classification
+   * @param {string} errorType - The type of error (wrapped_tool, unrecognized_tool, no_tool_call, circuit_breaker, etc.)
+   * @param {Object} errorDetails - Error details including message, stack, context
+   */
+  recordErrorEvent(errorType, errorDetails = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent(`error.${errorType}`, {
+      'session.id': this.sessionId,
+      'error.type': errorType,
+      'error.message': errorDetails.message?.substring(0, 1000) || null,
+      'error.stack': errorDetails.stack?.substring(0, 2000) || null,
+      'error.recoverable': errorDetails.recoverable ?? true,
+      'error.context': JSON.stringify(errorDetails.context || {}).substring(0, 1000),
+      ...Object.fromEntries(
+        Object.entries(errorDetails)
+          .filter(([k]) => !['message', 'stack', 'context', 'recoverable'].includes(k))
+          .map(([k, v]) => [`error.${k}`, v])
+      )
+    });
+  }
+
+  /**
+   * Record AI thinking/reasoning content
+   * @param {string} thinkingContent - The thinking content from AI response
+   * @param {Object} metadata - Additional metadata
+   */
+  recordThinkingContent(thinkingContent, metadata = {}) {
+    if (!this.isEnabled() || !thinkingContent) return;
+
+    this.addEvent('ai.thinking', {
+      'session.id': this.sessionId,
+      'ai.thinking.content': thinkingContent.substring(0, 50000),
+      'ai.thinking.length': thinkingContent.length,
+      'ai.thinking.hash': this.hashContent(thinkingContent),
+      ...metadata
+    });
+  }
+
+  /**
+   * Record AI tool call decision
+   * @param {string} toolName - The tool name AI decided to call
+   * @param {Object} params - The parameters AI provided
+   * @param {Object} metadata - Additional metadata
+   */
+  recordToolDecision(toolName, params, metadata = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent('ai.tool_decision', {
+      'session.id': this.sessionId,
+      'ai.tool_decision.name': toolName,
+      'ai.tool_decision.params': JSON.stringify(params || {}).substring(0, 2000),
+      ...metadata
+    });
+  }
+
+  /**
+   * Record tool result after execution
+   * @param {string} toolName - The tool that was executed
+   * @param {string|Object} result - The tool result
+   * @param {boolean} success - Whether the tool succeeded
+   * @param {number} durationMs - Execution duration in milliseconds
+   * @param {Object} metadata - Additional metadata
+   */
+  recordToolResult(toolName, result, success, durationMs, metadata = {}) {
+    if (!this.isEnabled()) return;
+
+    const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
+    this.addEvent('tool.result', {
+      'session.id': this.sessionId,
+      'tool.name': toolName,
+      'tool.result': resultStr.substring(0, 10000),
+      'tool.result.length': resultStr.length,
+      'tool.result.hash': this.hashContent(resultStr),
+      'tool.duration_ms': durationMs,
+      'tool.success': success,
+      ...metadata
+    });
+  }
+
+  /**
+   * Record MCP tool execution start
+   * @param {string} toolName - MCP tool name
+   * @param {string} serverName - MCP server name
+   * @param {Object} params - Tool parameters
+   * @param {Object} metadata - Additional metadata
+   */
+  recordMcpToolStart(toolName, serverName, params, metadata = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent('mcp.tool.start', {
+      'session.id': this.sessionId,
+      'mcp.tool.name': toolName,
+      'mcp.tool.server': serverName || 'unknown',
+      'mcp.tool.params': JSON.stringify(params || {}).substring(0, 2000),
+      ...metadata
+    });
+  }
+
+  /**
+   * Record MCP tool execution end
+   * @param {string} toolName - MCP tool name
+   * @param {string} serverName - MCP server name
+   * @param {string|Object} result - Tool result
+   * @param {boolean} success - Whether succeeded
+   * @param {number} durationMs - Execution duration
+   * @param {string} errorMessage - Error message if failed
+   * @param {Object} metadata - Additional metadata
+   */
+  recordMcpToolEnd(toolName, serverName, result, success, durationMs, errorMessage = null, metadata = {}) {
+    if (!this.isEnabled()) return;
+
+    const resultStr = typeof result === 'string' ? result : JSON.stringify(result || '');
+    this.addEvent('mcp.tool.end', {
+      'session.id': this.sessionId,
+      'mcp.tool.name': toolName,
+      'mcp.tool.server': serverName || 'unknown',
+      'mcp.tool.result': resultStr.substring(0, 10000),
+      'mcp.tool.result.length': resultStr.length,
+      'mcp.tool.duration_ms': durationMs,
+      'mcp.tool.success': success,
+      'mcp.tool.error': errorMessage,
+      ...metadata
+    });
+  }
+
+  /**
+   * Record iteration lifecycle event
+   * @param {string} eventType - start or end
+   * @param {number} iteration - Iteration number
+   * @param {Object} data - Additional data
+   */
+  recordIterationEvent(eventType, iteration, data = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent(`iteration.${eventType}`, {
+      'session.id': this.sessionId,
+      'iteration': iteration,
+      ...data
+    });
+  }
+
+  /**
+   * Record per-turn token breakdown
+   * @param {number} iteration - Iteration number
+   * @param {Object} tokenData - Token metrics
+   */
+  recordTokenTurn(iteration, tokenData = {}) {
+    if (!this.isEnabled()) return;
+
+    this.addEvent('tokens.turn', {
+      'session.id': this.sessionId,
+      'iteration': iteration,
+      'tokens.input': tokenData.inputTokens || 0,
+      'tokens.output': tokenData.outputTokens || 0,
+      'tokens.total': (tokenData.inputTokens || 0) + (tokenData.outputTokens || 0),
+      'tokens.cache_read': tokenData.cacheReadTokens || 0,
+      'tokens.cache_write': tokenData.cacheWriteTokens || 0,
+      'tokens.context_used': tokenData.contextTokens || 0,
+      'tokens.context_remaining': tokenData.maxContextTokens ? (tokenData.maxContextTokens - (tokenData.contextTokens || 0)) : null
+    });
+  }
+
   async withSpan(spanName, fn, attributes = {}) {
     if (!this.isEnabled()) {
       return fn();

package/build/agent/tools.js

@@ -270,13 +270,16 @@ User: Analyze the diagram in docs/architecture.svg
  */
 export function parseXmlToolCallWithThinking(xmlString, validTools) {
   // Use the shared processing logic
-  const { cleanedXmlString, recoveryResult } = processXmlWithThinkingAndRecovery(xmlString, validTools);
-  
-  // If recovery found an attempt_complete pattern, return it
+  const { cleanedXmlString, recoveryResult, thinkingContent } = processXmlWithThinkingAndRecovery(xmlString, validTools);
+
+  // If recovery found an attempt_complete pattern, return it with thinking content
   if (recoveryResult) {
-    return recoveryResult;
+    return { ...recoveryResult, thinkingContent };
   }
 
   // Otherwise, use the original parseXmlToolCall function to parse the cleaned XML string
-  return parseXmlToolCall(cleanedXmlString, validTools);
+  const toolCall = parseXmlToolCall(cleanedXmlString, validTools);
+
+  // Return tool call with thinking content attached
+  return toolCall ? { ...toolCall, thinkingContent } : null;
 }

package/build/tools/analyzeAll.js

@@ -514,6 +514,7 @@ export async function analyzeAll(options) {
 		sessionId,
 		debug = false,
 		cwd,
+		workspaceRoot,
 		allowedFolders,
 		provider,
 		model,
@@ -527,10 +528,14 @@ export async function analyzeAll(options) {
 		throw new Error('The "question" parameter is required.');
 	}
 
+	// Use workspaceRoot (computed common prefix) for consistent path handling
+	// Consistent fallback chain: workspaceRoot > cwd > allowedFolders[0] > path
+	const effectiveWorkspaceRoot = workspaceRoot || cwd || allowedFolders?.[0] || path;
+
 	const delegateOptions = {
 		debug,
 		sessionId,
-		path: allowedFolders?.[0] || cwd || path,
+		path: effectiveWorkspaceRoot,
 		allowedFolders,
 		provider,
 		model,

package/build/tools/bash.js

@@ -7,6 +7,7 @@ import { tool } from 'ai';
 import { resolve, isAbsolute, sep } from 'path';
 import { BashPermissionChecker } from '../agent/bashPermissions.js';
 import { executeBashCommand, formatExecutionResult, validateExecutionOptions } from '../agent/bashExecutor.js';
+import { toRelativePath, safeRealpath } from '../utils/path-validation.js';
 
 /**
  * Bash tool generator
@@ -32,9 +33,14 @@ export const bashTool = (options = {}) => {
     debug = false,
     cwd,
     allowedFolders = [],
+    workspaceRoot: providedWorkspaceRoot,
     tracer = null
   } = options;
 
+  // Compute workspaceRoot with proper fallback chain
+  // Priority: explicit workspaceRoot > cwd > allowedFolders[0] > process.cwd()
+  const workspaceRoot = providedWorkspaceRoot || cwd || (allowedFolders.length > 0 && allowedFolders[0]) || process.cwd();
+
   // Create permission checker with tracer for telemetry
   const permissionChecker = new BashPermissionChecker({
     allow: bashConfig.allow,
@@ -46,6 +52,7 @@ export const bashTool = (options = {}) => {
   });
 
   // Determine default working directory
+  // Priority: explicit bashConfig.workingDirectory > cwd (which defaults to workspaceRoot) > fallback
   const getDefaultWorkingDirectory = () => {
     if (bashConfig.workingDirectory) {
       return bashConfig.workingDirectory;
@@ -53,6 +60,10 @@ export const bashTool = (options = {}) => {
     if (cwd) {
       return cwd;
     }
+    // Use workspaceRoot (computed common prefix) for consistency with other tools
+    if (workspaceRoot) {
+      return workspaceRoot;
+    }
     if (allowedFolders && allowedFolders.length > 0) {
       return allowedFolders[0];
     }
@@ -154,16 +165,20 @@ For code exploration, try these safe alternatives:
 
         // Validate working directory is within allowed folders if specified
         if (allowedFolders && allowedFolders.length > 0) {
-          const resolvedWorkingDir = resolve(workingDir);
+          // Use safeRealpath to resolve symlinks for security
+          // This prevents symlink bypass attacks (e.g., /tmp -> /private/tmp on macOS)
+          const resolvedWorkingDir = safeRealpath(workingDir);
           const isAllowed = allowedFolders.some(folder => {
-            const resolvedFolder = resolve(folder);
+            const resolvedFolder = safeRealpath(folder);
             // Use exact match OR startsWith with separator to prevent bypass attacks
             // e.g., '/tmp-malicious' should NOT match allowed folder '/tmp'
             return resolvedWorkingDir === resolvedFolder || resolvedWorkingDir.startsWith(resolvedFolder + sep);
           });
 
           if (!isAllowed) {
-            return `Error: Working directory "${workingDir}" is not within allowed folders: ${allowedFolders.join(', ')}`;
+            const relativeDir = toRelativePath(workingDir, workspaceRoot);
+            const relativeAllowed = allowedFolders.map(f => toRelativePath(f, workspaceRoot));
+            return `Error: Working directory "${relativeDir}" is not within allowed folders: ${relativeAllowed.join(', ')}`;
           }
         }
 

package/build/tools/edit.js

@@ -7,6 +7,7 @@ import { tool } from 'ai';
 import { promises as fs } from 'fs';
 import { dirname, resolve, isAbsolute, sep } from 'path';
 import { existsSync } from 'fs';
+import { toRelativePath, safeRealpath } from '../utils/path-validation.js';
 
 /**
  * Validates that a path is within allowed directories
@@ -17,15 +18,18 @@ import { existsSync } from 'fs';
 function isPathAllowed(filePath, allowedFolders) {
   if (!allowedFolders || allowedFolders.length === 0) {
     // If no restrictions, allow current directory and below
-    const resolvedPath = resolve(filePath);
-    const cwd = resolve(process.cwd());
+    // Use safeRealpath to resolve symlinks for security
+    const resolvedPath = safeRealpath(filePath);
+    const cwd = safeRealpath(process.cwd());
     // Ensure proper path separator to prevent path traversal
     return resolvedPath === cwd || resolvedPath.startsWith(cwd + sep);
   }
 
-  const resolvedPath = resolve(filePath);
+  // Use safeRealpath to resolve symlinks for security
+  // This prevents symlink bypass attacks (e.g., /tmp -> /private/tmp on macOS)
+  const resolvedPath = safeRealpath(filePath);
   return allowedFolders.some(folder => {
-    const allowedPath = resolve(folder);
+    const allowedPath = safeRealpath(folder);
     // Ensure proper path separator to prevent path traversal
     return resolvedPath === allowedPath || resolvedPath.startsWith(allowedPath + sep);
   });
@@ -37,10 +41,13 @@ function isPathAllowed(filePath, allowedFolders) {
  * @returns {Object} Parsed configuration
  */
 function parseFileToolOptions(options = {}) {
+  const allowedFolders = options.allowedFolders || [];
   return {
     debug: options.debug || false,
-    allowedFolders: options.allowedFolders || [],
-    cwd: options.cwd
+    allowedFolders,
+    cwd: options.cwd,
+    // Consistent fallback chain: workspaceRoot > cwd > allowedFolders[0] > process.cwd()
+    workspaceRoot: options.workspaceRoot || options.cwd || (allowedFolders.length > 0 && allowedFolders[0]) || process.cwd()
   };
 }
 
@@ -54,7 +61,7 @@ function parseFileToolOptions(options = {}) {
  * @returns {Object} Configured edit tool
  */
 export const editTool = (options = {}) => {
-  const { debug, allowedFolders, cwd } = parseFileToolOptions(options);
+  const { debug, allowedFolders, cwd, workspaceRoot } = parseFileToolOptions(options);
 
   return tool({
     name: 'edit',
@@ -119,7 +126,8 @@ Important:
 
         // Check if path is allowed
         if (!isPathAllowed(resolvedPath, allowedFolders)) {
-          return `Error editing file: Permission denied - ${file_path} is outside allowed directories`;
+          const relativePath = toRelativePath(resolvedPath, workspaceRoot);
+          return `Error editing file: Permission denied - ${relativePath} is outside allowed directories`;
         }
 
         // Check if file exists
@@ -186,7 +194,7 @@ Important:
  * @returns {Object} Configured create tool
  */
 export const createTool = (options = {}) => {
-  const { debug, allowedFolders, cwd } = parseFileToolOptions(options);
+  const { debug, allowedFolders, cwd, workspaceRoot } = parseFileToolOptions(options);
 
   return tool({
     name: 'create',
@@ -243,7 +251,8 @@ Important:
 
         // Check if path is allowed
         if (!isPathAllowed(resolvedPath, allowedFolders)) {
-          return `Error creating file: Permission denied - ${file_path} is outside allowed directories`;
+          const relativePath = toRelativePath(resolvedPath, workspaceRoot);
+          return `Error creating file: Permission denied - ${relativePath} is outside allowed directories`;
         }
 
         // Check if file exists

package/build/tools/vercel.js

@@ -471,7 +471,7 @@ export const extractTool = (options = {}) => {
  * @returns {Object} Configured delegate tool
  */
 export const delegateTool = (options = {}) => {
-	const { debug = false, timeout = 300, cwd, allowedFolders, enableBash = false, bashConfig, architectureFileName, enableMcp = false, mcpConfig = null, mcpConfigPath = null, delegationManager = null } = options;
+	const { debug = false, timeout = 300, cwd, allowedFolders, workspaceRoot, enableBash = false, bashConfig, architectureFileName, enableMcp = false, mcpConfig = null, mcpConfigPath = null, delegationManager = null } = options;
 
 	return tool({
 		name: 'delegate',
@@ -521,7 +521,7 @@ export const delegateTool = (options = {}) => {
 			// NOTE: Delegation intentionally uses DIFFERENT priority than other tools.
 			//
 			// Other tools (search, extract, query, bash) use: cwd || allowedFolders[0]
-			// Delegation uses: path || allowedFolders[0] || cwd
+			// Delegation uses: path || workspaceRoot || cwd
 			//
 			// This is intentional because:
 			// - Other tools operate within the parent's navigation context (cwd is correct)
@@ -529,10 +529,15 @@ export const delegateTool = (options = {}) => {
 			// - Using parent's cwd would cause "path doubling" (Issue #348) where paths like
 			//   /workspace/project/src/internal/build/src/internal/build/file.go get constructed
 			//
-			// The workspace root (allowedFolders[0]) is the security boundary and correct base
-			// for subagent operations. Parent navigation context should not leak to subagents.
-			const workspaceRoot = allowedFolders && allowedFolders[0];
-			const effectivePath = path || workspaceRoot || cwd;
+			// The workspace root (computed as common prefix of allowedFolders) is the security
+			// boundary and correct base for subagent operations. Parent navigation context
+			// should not leak to subagents.
+			//
+			// NOTE: This priority (workspaceRoot > allowedFolders[0], excluding cwd) is INTENTIONALLY
+			// different from other tools (bashTool uses workspaceRoot > cwd > allowedFolders[0]).
+			// This prevents parent's navigation state from leaking to subagents.
+			const effectiveWorkspaceRoot = workspaceRoot || (allowedFolders && allowedFolders[0]);
+			const effectivePath = path || effectiveWorkspaceRoot || cwd;
 
 			if (debug) {
 				console.error(`Executing delegate with task: "${task.substring(0, 100)}${task.length > 100 ? '...' : ''}"`);
@@ -586,7 +591,7 @@ export const delegateTool = (options = {}) => {
  * @returns {Object} Configured analyze_all tool
  */
 export const analyzeAllTool = (options = {}) => {
-	const { sessionId, debug = false, delegationManager = null } = options;
+	const { sessionId, debug = false, delegationManager = null, workspaceRoot } = options;
 
 	return tool({
 		name: 'analyze_all',
@@ -609,12 +614,17 @@ export const analyzeAllTool = (options = {}) => {
 					console.error(`[analyze_all] Path: ${searchPath}`);
 				}
 
+				// Use workspaceRoot (computed common prefix) for consistent path handling
+				// Priority: workspaceRoot > cwd > allowedFolders[0] (consistent with bashTool)
+				const effectiveWorkspaceRoot = workspaceRoot || options.cwd || (options.allowedFolders && options.allowedFolders[0]);
+
 				const result = await analyzeAll({
 					question,
 					path: searchPath,
 					sessionId,
 					debug,
 					cwd: options.cwd,
+					workspaceRoot: effectiveWorkspaceRoot,
 					allowedFolders: options.allowedFolders,
 					provider: options.provider,
 					model: options.model,

package/build/utils/path-validation.js

@@ -4,9 +4,48 @@
  */
 
 import path from 'path';
-import { promises as fs } from 'fs';
+import { promises as fs, realpathSync } from 'fs';
 import { PathError } from './error-types.js';
 
+/**
+ * Safely resolve symlinks for a path.
+ * Returns the real path if it exists, otherwise finds the nearest existing
+ * ancestor directory and resolves it, then appends the remaining path components.
+ * This is important for security to prevent symlink bypass attacks.
+ *
+ * @param {string} inputPath - Path to resolve
+ * @returns {string} Resolved real path or best-effort resolved path
+ */
+export function safeRealpath(inputPath) {
+	try {
+		return realpathSync(inputPath);
+	} catch (error) {
+		// If path doesn't exist, find the nearest existing ancestor
+		// and resolve it, then append the remaining components.
+		// This handles cases like non-existent nested paths where an ancestor
+		// may be a symlink (e.g., /var -> /private/var on macOS)
+		const normalized = path.normalize(inputPath);
+		const parts = normalized.split(path.sep);
+
+		// Try progressively shorter paths until we find one that exists
+		for (let i = parts.length - 1; i >= 0; i--) {
+			const ancestorPath = parts.slice(0, i).join(path.sep) || path.sep;
+			try {
+				const resolvedAncestor = realpathSync(ancestorPath);
+				// Found an existing ancestor - append remaining components
+				const remainingParts = parts.slice(i);
+				return path.join(resolvedAncestor, ...remainingParts);
+			} catch (ancestorError) {
+				// This ancestor doesn't exist either, try the next one up
+				continue;
+			}
+		}
+
+		// No existing ancestor found, return normalized path
+		return normalized;
+	}
+}
+
 /**
  * Validates and normalizes a path to be used as working directory (cwd).
  *
@@ -74,3 +113,111 @@ export function normalizePath(inputPath, defaultPath = process.cwd()) {
 	const targetPath = inputPath || defaultPath;
 	return path.normalize(path.resolve(targetPath));
 }
+
+/**
+ * Compute the common prefix (workspace root) from an array of folder paths.
+ * This is useful for finding a single workspace root from multiple allowed folders.
+ *
+ * IMPORTANT: This function returns a value for DISPLAY and CWD purposes only.
+ * It is NOT a security boundary. All security checks should be performed against
+ * the original allowedFolders array, not against workspaceRoot.
+ *
+ * When no common prefix exists (e.g., unrelated paths), returns the first folder.
+ * This is intentional - the caller should use allowedFolders for security validation.
+ *
+ * Examples:
+ * - ['/tmp/ws/tyk', '/tmp/ws/tyk-docs'] -> '/tmp/ws'
+ * - ['/tmp/ws/tyk'] -> '/tmp/ws/tyk'
+ * - ['/a/b', '/c/d'] -> '/a/b' (no common prefix, returns first folder for cwd)
+ * - ['C:\\Users\\ws\\tyk', 'C:\\Users\\ws\\docs'] -> 'C:\\Users\\ws' (Windows)
+ *
+ * @param {string[]} folders - Array of absolute folder paths
+ * @returns {string} Common prefix path (for display/cwd, NOT security boundary)
+ */
+export function getCommonPrefix(folders) {
+	if (!folders || folders.length === 0) {
+		return process.cwd();
+	}
+
+	if (folders.length === 1) {
+		// Resolve symlinks for security
+		return safeRealpath(folders[0]);
+	}
+
+	// Resolve symlinks and normalize all paths to handle mixed separators
+	// This prevents symlink bypass attacks where a symlink could point outside the workspace
+	const normalized = folders.map(f => safeRealpath(f));
+
+	// Split into segments
+	const segments = normalized.map(f => f.split(path.sep));
+
+	// Find minimum length
+	const minLen = Math.min(...segments.map(s => s.length));
+
+	// Find common prefix segments
+	const commonSegments = [];
+	for (let i = 0; i < minLen; i++) {
+		const segment = segments[0][i];
+		if (segments.every(s => s[i] === segment)) {
+			commonSegments.push(segment);
+		} else {
+			break;
+		}
+	}
+
+	// Handle edge cases
+	if (commonSegments.length === 0) {
+		// No common prefix at all, return first folder
+		return normalized[0];
+	}
+
+	// Handle Windows drive letters (e.g., 'C:')
+	// If only the drive letter is common, return first folder for more useful context
+	if (commonSegments.length === 1 && /^[a-zA-Z]:$/.test(commonSegments[0])) {
+		return normalized[0];
+	}
+
+	// Handle Unix root (empty string from split)
+	// If only the root '/' is common, return first folder for more useful context
+	if (commonSegments.length === 1 && commonSegments[0] === '') {
+		return normalized[0];
+	}
+
+	return commonSegments.join(path.sep);
+}
+
+/**
+ * Convert an absolute path to a relative path from the workspace root.
+ * Returns the original path if it cannot be made relative (outside workspace).
+ *
+ * @param {string} absolutePath - Absolute path to convert
+ * @param {string} workspaceRoot - Workspace root to compute relative path from
+ * @returns {string} Relative path or original if outside workspace
+ */
+export function toRelativePath(absolutePath, workspaceRoot) {
+	if (!absolutePath || !workspaceRoot) {
+		return absolutePath;
+	}
+
+	// Resolve symlinks for security to prevent bypass attacks
+	// Use safeRealpath which falls back to normalized path if resolution fails
+	let normalized = safeRealpath(absolutePath);
+	let normalizedRoot = safeRealpath(workspaceRoot);
+
+	// Remove trailing separators (path.normalize doesn't always do this)
+	while (normalizedRoot.length > 1 && normalizedRoot.endsWith(path.sep)) {
+		normalizedRoot = normalizedRoot.slice(0, -1);
+	}
+
+	// Check if path is within workspace (exact match or starts with root + separator)
+	if (normalized === normalizedRoot) {
+		return '.';
+	}
+
+	if (normalized.startsWith(normalizedRoot + path.sep)) {
+		return path.relative(normalizedRoot, normalized);
+	}
+
+	// Path is outside workspace, return as-is
+	return absolutePath;
+}