M.I.M.I.R - Multi-agent Intelligent Memory & Insight Repository

# Workspace Context Implementation Summary **Date**: November 18, 2025 **Status**: ✅ **COMPLETE** - Ready for testing --- ## What Was Implemented ### Problem Solved When using the VSCode extension with a Dockerized Mimir server, tool calls (file operations, shell commands) were executing in the **server's container directory** (e.g., `/app/`) instead of the **user's VSCode workspace** (e.g., `/Users/c815719/src/myproject`). ### Solution Implemented **automatic workspace context propagation** with **Docker path translation**: 1. ✅ VSCode extension sends workspace path with every chat request 2. ✅ Server translates host paths → container paths using volume mounts 3. ✅ Tools execute in correct workspace directory 4. ✅ Thread-safe context propagation using `AsyncLocalStorage` --- ## Files Modified ### Core Implementation 1. **`src/orchestrator/workspace-context.ts`** ✨ NEW - `AsyncLocalStorage` for thread-safe context - `translatePathToContainer()` for Docker path mapping - `getWorkingDirectory()` for tools to access context - Supports both Docker and local development 2. **`src/orchestrator/tools.ts`** 🔧 UPDATED - All tools now use `getWorkingDirectory()` instead of `process.cwd()` - `run_terminal_cmd` executes in workspace context - `grep` tool respects workspace context 3. **`src/orchestrator/llm-client.ts`** 🔧 UPDATED - Added `workingDirectory` parameter to `execute()` - Wraps execution in `runWithWorkspaceContext()` - Logs workspace context for debugging 4. **`src/api/chat-api.ts`** 🔧 UPDATED - `ChatCompletionRequest` accepts `working_directory` field - Passes `working_directory` to agent execution - Logs workspace info for debugging 5. **`vscode-extension/src/extension.ts`** 🔧 UPDATED - Automatically detects VSCode workspace folder - Sends `working_directory` with every chat request - Warns if no workspace is open 6. **`docker-compose.yml`** 🔧 UPDATED - Changed workspace mount from `:ro` (read-only) to read-write - Enables file creation/editing by LLM tools ### Documentation 7. **`docs/guides/VSCODE_WORKSPACE_INTEGRATION.md`** 📚 NEW - Comprehensive guide to workspace integration - Path translation rules and examples - Troubleshooting section - Security considerations --- ## How It Works ### Full Flow Example **User Action:** ``` 1. Open VSCode in: /Users/c815719/src/myproject 2. Type: @mimir create a file called test.py with print("hello") ``` **VSCode Extension:** ```typescript workspaceFolder = vscode.workspace.workspaceFolders[0]; workingDirectory = "/Users/c815719/src/myproject"; POST /v1/chat/completions { working_directory: "/Users/c815719/src/myproject", messages: [...] } ``` **Server (chat-api.ts):** ```typescript const { working_directory } = req.body; // working_directory = "/Users/c815719/src/myproject" await agent.execute(task, 0, max_tool_calls, undefined, working_directory); ``` **Agent (llm-client.ts):** ```typescript if (workingDirectory) { return runWithWorkspaceContext( { workingDirectory: "/Users/c815719/src/myproject" }, executeWithContext ); } ``` **Workspace Context (workspace-context.ts):** ```typescript // Docker path translation HOST_WORKSPACE_ROOT = "/Users/c815719/src" WORKSPACE_ROOT = "/workspace" translatePathToContainer("/Users/c815719/src/myproject") → relativePath = "myproject" → containerPath = "/workspace/myproject" ✅ ``` **Tools (tools.ts):** ```typescript // Inside edit_file tool const workingDir = getWorkingDirectory(); // workingDir = "/workspace/myproject" // Create file at correct location fs.writeFileSync(path.join(workingDir, "test.py"), content); ``` **Result:** ``` File created: /workspace/myproject/test.py (in container) → /Users/c815719/src/myproject/test.py (on host) ✅ ``` --- ## Configuration Requirements ### Environment Variables (Docker) Already configured in `docker-compose.yml`: ```yaml environment: - WORKSPACE_ROOT=/workspace - HOST_WORKSPACE_ROOT=${HOST_WORKSPACE_ROOT} volumes: - ${HOST_WORKSPACE_ROOT:-~/src}:/workspace # Default: ~/src ``` ### Default Behavior | Variable | Default | Can Override | |----------|---------|--------------| | `HOST_WORKSPACE_ROOT` | `~/src` | ✅ Yes (env var) | | `WORKSPACE_ROOT` | `/workspace` | ✅ Yes (change docker-compose) | ### To Use Different Root ```bash export HOST_WORKSPACE_ROOT=/Users/c815719/projects docker-compose up -d ``` --- ## Testing Instructions ### Prerequisites 1. ✅ Mimir server running in Docker 2. ✅ Workspace under `~/src/` (or configured `HOST_WORKSPACE_ROOT`) 3. ✅ VSCode extension built and installed ### Test 1: Verify Workspace Detection ```bash # In VSCode, open a project under ~/src/ # Example: ~/src/test-project # Open VSCode Chat panel @mimir what is the current working directory? # Expected output: Should show /workspace/test-project (container path) # Server logs should show: # 📁 Workspace folder: /Users/c815719/src/test-project # 📁 Path translation: /Users/c815719/src/test-project → /workspace/test-project ``` ### Test 2: List Files ```bash @mimir list all files in the current directory # Should show files from your VSCode workspace # Server logs: "Command executed in /workspace/test-project" ``` ### Test 3: Create File ```bash @mimir create a file called hello.txt with "Hello from Mimir!" # Expected: # 1. File created at /workspace/test-project/hello.txt (container) # 2. File appears at ~/src/test-project/hello.txt (host) ✅ # 3. VSCode shows the new file immediately ``` ### Test 4: Edit File ```bash @mimir edit hello.txt and change the text to "Updated by Mimir" # Expected: # 1. File edited in container # 2. Changes visible in VSCode ``` ### Test 5: Run Commands ```bash @mimir run "ls -la" command # Expected: # - Command executes in /workspace/test-project # - Shows files from your VSCode workspace ``` ### Test 6: Path Outside Mounted Root (Should Warn) ```bash # Open a project OUTSIDE ~/src/ (e.g., ~/Documents/project) @mimir list files # Expected: # - Server logs warning: "Path not under HOST_WORKSPACE_ROOT" # - Tools may fail or use wrong directory ``` --- ## Server Logs to Watch When testing, monitor Docker logs: ```bash docker logs -f mimir_server ``` Look for: ✅ **Success indicators:** ``` 📁 Workspace folder: /Users/c815719/src/test-project 📁 Workspace context: /workspace/test-project 📁 Path translation: /Users/c815719/src/test-project → /workspace/test-project Host root: /Users/c815719/src → Container root: /workspace ``` ⚠️ **Warning indicators:** ``` ⚠️ No workspace folder open - tools will use server's working directory ⚠️ Path /Users/c815719/Documents/project is not under HOST_WORKSPACE_ROOT ``` --- ## Troubleshooting ### Issue: Files Created in Wrong Location **Check 1**: Workspace mounted? ```bash docker exec mimir_server ls -la /workspace # Should show your project files ``` **Check 2**: Environment variables set? ```bash docker exec mimir_server env | grep WORKSPACE # Should show: # WORKSPACE_ROOT=/workspace # HOST_WORKSPACE_ROOT=/Users/c815719/src ``` **Check 3**: VSCode workspace under mounted path? ```bash # If workspace is /Users/c815719/Documents/project # But HOST_WORKSPACE_ROOT is ~/src # → Won't work! Move project to ~/src/ ``` ### Issue: Permission Denied **Check**: Volume mount is read-write ```yaml volumes: - ~/src:/workspace # ✅ Read-write (correct) # NOT: - ~/src:/workspace:ro # ❌ Read-only (wrong) ``` ### Issue: No Workspace Context Logs **Check**: VSCode workspace open? ```typescript // In VSCode, ensure you have a folder open // File → Open Folder → Select project under ~/src/ ``` --- ## Architecture Benefits ### 1. Thread-Safe - ✅ Uses `AsyncLocalStorage` - no global state pollution - ✅ Each request has isolated context - ✅ Safe for concurrent requests ### 2. Zero Config for Users - ✅ VSCode extension auto-detects workspace - ✅ Path translation automatic - ✅ Works out-of-the-box with default Docker setup ### 3. Backwards Compatible - ✅ Non-Docker setup: No changes needed (paths used as-is) - ✅ Web Portal: Still works (uses server's cwd) - ✅ Direct API calls: Optional `working_directory` field ### 4. Secure by Design - ✅ Tools only access mounted workspace (not entire filesystem) - ✅ Read-write mount limited to specific directory - ✅ Path validation prevents directory traversal --- ## Next Steps ### 1. Test in Your Environment - [ ] Open VSCode in a project under `~/src/` - [ ] Test file operations with `@mimir` - [ ] Verify files appear in correct location - [ ] Check server logs for path translation ### 2. Configure for Your Setup (Optional) - [ ] If projects are NOT under `~/src/`, set `HOST_WORKSPACE_ROOT` - [ ] Update `.bashrc`/`.zshrc` with export - [ ] Restart Docker Compose ### 3. Studio Integration (Future) - [ ] Studio workflows will use same mechanism - [ ] Pass `working_directory` in workflow JSON - [ ] Same path translation applies ### 4. Documentation Updates (Complete) - [x] Implementation guide created - [x] User-facing docs created - [x] Troubleshooting section added - [x] Examples provided --- ## Summary ✅ **Complete Implementation:** - Workspace context propagation - Docker path translation - Thread-safe context isolation - Automatic workspace detection in VSCode - Comprehensive documentation 🎯 **Ready for:** - VSCode extension chat (`@mimir`) - Studio workflow execution (future) - Both Docker and local development 📚 **See Also:** - `docs/guides/VSCODE_WORKSPACE_INTEGRATION.md` - User guide - `vscode-extension/STUDIO_POC.md` - VSCode extension POC - `src/orchestrator/workspace-context.ts` - Implementation --- **Status**: ✅ **READY TO TEST** **Next**: Follow testing instructions above to verify in your environment