From 956d136709983b9d96fd4a5b36c5b1201da75baa Mon Sep 17 00:00:00 2001 From: Marc Goodner Date: Mon, 5 Jan 2026 19:38:06 -0800 Subject: [PATCH 1/2] Add test for colon sanitization in agent names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Windows does not allow colons in file/directory names (except for drive letters like C:, D:). Agent names like "foundation:explorer" need to be sanitized when used in session IDs that become directory paths on the filesystem. The existing sanitization code (line 76 in tracing.py) already handles this correctly by replacing all non-alphanumeric characters with hyphens via regex: [^a-z0-9]+ → - This test documents and verifies this critical behavior for Windows compatibility, ensuring that agent names like "foundation:explorer" become "foundation-explorer" in session IDs. Fixes issue where Windows users see: "[WinError 267] The directory name is invalid" when sub-sessions use agent names containing colons. Type: test 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- tests/test_tracing.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/test_tracing.py b/tests/test_tracing.py index cd846e2..7406104 100644 --- a/tests/test_tracing.py +++ b/tests/test_tracing.py @@ -74,3 +74,11 @@ def test_hyphenated_agent_name_preserved(self) -> None: """Hyphenated agent names are preserved.""" sub_id = generate_sub_session_id(agent_name="zen-architect") assert sub_id.endswith("_zen-architect") + + def test_colon_in_agent_name_sanitized(self) -> None: + """Colons in agent names are replaced with hyphens (Windows filesystem compatibility).""" + sub_id = generate_sub_session_id(agent_name="foundation:explorer") + # Colon should be replaced with hyphen + assert sub_id.endswith("_foundation-explorer") + # Verify no colons in the entire ID (Windows doesn't allow colons in paths) + assert ":" not in sub_id From 50df8017847844a0438ac0266b39c69a4efbde5c Mon Sep 17 00:00:00 2001 From: Marc Goodner Date: Mon, 5 Jan 2026 20:02:17 -0800 Subject: [PATCH 2/2] Document Windows compatibility practices in IMPLEMENTATION_PHILOSOPHY.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive guidance for cross-platform development with focus on Windows compatibility. This documents critical patterns discovered from fixing production issues: 1. **File I/O Encoding**: Always specify encoding="utf-8" explicitly - Windows defaults to cp1252/charmap instead of UTF-8 - Prevents "'charmap' codec can't decode" errors - Applies to open(), Path.read_text(), Path.write_text() 2. **Path Sanitization**: Remove Windows-prohibited characters - Colons, pipes, asterisks, etc. cause [WinError 267] - Agent names like "foundation:explorer" must be sanitized - Applies to any user input used in filenames 3. **Development Checklist**: Pre-commit verification steps This guidance is loaded by all agents via common-agent-base.md, ensuring consistent Windows-safe code across the codebase. Related PRs: - amplifier-app-cli#36 (encoding fixes) - Merged - amplifier-foundation#11 (test coverage) - Open Type: docs 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- context/IMPLEMENTATION_PHILOSOPHY.md | 92 ++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/context/IMPLEMENTATION_PHILOSOPHY.md b/context/IMPLEMENTATION_PHILOSOPHY.md index cea13b4..7c8c0fc 100644 --- a/context/IMPLEMENTATION_PHILOSOPHY.md +++ b/context/IMPLEMENTATION_PHILOSOPHY.md @@ -295,11 +295,103 @@ class EnhancedMcpClient: # [50+ more lines of complex state tracking and retry logic] ``` +## Cross-Platform Development (Windows Compatibility) + +### File I/O - Always Specify UTF-8 Encoding + +**Critical Rule**: Every file operation must explicitly specify `encoding="utf-8"` + +**Why**: Windows defaults to `cp1252` (or locale-specific "charmap" encoding) instead of UTF-8. Python's `open()` and `Path.read_text()` use system default encoding when not specified, causing decode errors with UTF-8 content on Windows. + +**Error signature**: `'charmap' codec can't decode byte 0x9d in position X: character maps to ` + +**Always do this:** +```python +# ✅ Reading files +with open(path, encoding="utf-8") as f: + content = f.read() + +config = Path(file).read_text(encoding="utf-8") + +# ✅ Writing files +with open(path, "w", encoding="utf-8") as f: + f.write(content) + +Path(file).write_text(content, encoding="utf-8") +``` + +**Never do this:** +```python +# ❌ Windows-unsafe (uses system default encoding) +with open(path) as f: + content = f.read() + +config = Path(file).read_text() +``` + +### Path and Filename Sanitization + +**Critical Rule**: Any user input or external data used in filenames must be sanitized for Windows compatibility. + +**Windows-prohibited characters**: `< > : " | ? * \` + +**Why**: Windows reserves these characters for special purposes. Colons (`:`) are particularly problematic - reserved for drive letters only (e.g., `C:`), causing `[WinError 267] The directory name is invalid`. + +**Common sources of problematic characters:** +- Agent names with colons: `foundation:explorer` +- User input in filenames +- URL-derived identifiers +- Timestamps with colons + +**Sanitization patterns:** +```python +# ✅ For filesystem-safe identifiers (agent names, session IDs) +import re +sanitized = re.sub(r"[^a-z0-9]+", "-", name.lower()) +sanitized = re.sub(r"-{2,}", "-", sanitized) # Collapse multiple hyphens +sanitized = sanitized.strip("-").lstrip(".") # Remove leading/trailing + +# ✅ For project slugs from paths +slug = str(path).replace("/", "-").replace("\\", "-").replace(":", "") + +# ✅ Minimal sanitization (preserve more characters) +sanitized = re.sub(r'[<>:"|?*\\]', "-", filename) +``` + +**Examples:** +- `foundation:explorer` → `foundation-explorer` +- `My Agent!` → `my-agent` +- `C:\Users\name` → `C-Users-name` + +### Development Checklist for Windows Compatibility + +Before committing code that touches file I/O or paths: +- [ ] All `open()` calls include `encoding="utf-8"` +- [ ] All `Path.read_text()` / `write_text()` include `encoding="utf-8"` +- [ ] Any filename/path generation sanitizes Windows-prohibited characters +- [ ] No assumptions about case-sensitive filesystems +- [ ] No assumptions about path separator types (`/` vs `\`) + +### Testing on Windows + +**High-risk scenarios to test:** +- File I/O with UTF-8 content (emojis, special characters, non-ASCII) +- Filenames/paths containing colons or other prohibited characters +- Long paths (Windows 260 character limit before long path support) +- Case sensitivity assumptions (Windows is case-insensitive by default) + +**Recommended test environments:** +- Windows 10/11 native Python (primary target) +- PowerShell and Command Prompt +- Consider WSL for Unix-compatibility testing + ## Remember - It's easier to add complexity later than to remove it - Code you don't write has no bugs - Favor clarity over cleverness - The best code is often the simplest +- **Always specify UTF-8 encoding for cross-platform compatibility** +- **Always sanitize user input used in filenames** This philosophy document serves as the foundational guide for all implementation decisions in the project.