Skip to content

Self-improving AI Employees for everyone

fix(terminal): strip ANSI escape codes from captured terminal output

trohitg62d577abdd0f
diff --git a/docs-internal/node-logic-flows/code_fs_process/processManager.md b/docs-internal/node-logic-flows/code_fs_process/processManager.md
index 3e9b1f9f..1c6b65c3 100644
--- a/docs-internal/node-logic-flows/code_fs_process/processManager.md
+++ b/docs-internal/node-logic-flows/code_fs_process/processManager.md
@@ -113,6 +113,13 @@ flowchart TD
- **PATH inheritance**: `env = {**os.environ, "PYTHONUNBUFFERED": "1"}`.
The full system PATH is available - this is the main distinction from the
sandboxed shell node.
+- **ANSI-stripped at capture**: `_read_stream` runs each decoded line through
+ `core.ansi.strip_ansi` (a wrapper over **`click.unstyle`**) BEFORE the log-file
+ write / `broadcast_terminal_log` / `line_handler`, so colour + cursor/erase
+ codes from build tools (`vite`/`npm`/…) render as clean text in the Terminal
+ tab, the persisted logs, and `get_output`. `click.unstyle` is byte-faithful
+ apart from the stripped escapes (unlike `rich.Text.from_ansi`, which drops
+ trailing newlines).
- **Exit code capture**: only the stdout reader task fulfils `exit_code` on
EOF via `process.wait()` with a 5s timeout. Status becomes `stopped`
(exit=0) or `error` (nonzero).
diff --git a/docs-internal/node-logic-flows/code_fs_process/shell.md b/docs-internal/node-logic-flows/code_fs_process/shell.md
index aaab1281..31f92ffc 100644
--- a/docs-internal/node-logic-flows/code_fs_process/shell.md
+++ b/docs-internal/node-logic-flows/code_fs_process/shell.md
@@ -46,7 +46,7 @@ servicing other requests while the command executes.
```ts
{
- stdout: string; // Combined output (backend merges stderr into stdout unless truncated)
+ stdout: string; // Combined output (backend merges stderr into stdout unless truncated); ANSI-stripped
exit_code: number; // 124 = timed out, else the process exit code
truncated: boolean; // Whether the backend truncated the output buffer
command: string; // Echo of the requested command
@@ -85,6 +85,11 @@ flowchart TD
- **Truncation**: the backend caps output size internally; when capped
`truncated=true` surfaces to the caller. The exact cap lives in
`deepagents`.
+- **ANSI stripping**: `result.output` is run through `core.ansi.strip_ansi`
+ (a wrapper over **`click.unstyle`**) before being returned as `stdout` (and
+ before the operator-log line), so colour/cursor codes from tools like
+ `vite`/`npm` don't render as garbage in the Output panel. `click.unstyle` is
+ byte-faithful apart from the stripped escapes.
- **Broad `except Exception`**: backend failures (missing binary,
`virtual_mode` violations) become an error envelope.
diff --git a/server/core/ansi.py b/server/core/ansi.py
new file mode 100644
index 00000000..d2efd7c8
--- /dev/null
+++ b/server/core/ansi.py
@@ -0,0 +1,34 @@
+"""Strip ANSI escape sequences from captured terminal output.
+
+Subprocess output (vite / npm / git / etc.) embeds ANSI CSI colour and
+cursor-control codes. MachinaOs renders terminal output as plain text — the
+Terminal tab (``process_service`` broadcasts + log files) and node Output panels
+(the shell node's ``stdout``) — so the raw codes surface as garbage like
+``[36mvite v7.3.3[39m``. Strip them at the capture boundary so stored logs,
+broadcasts, and node outputs are all clean.
+
+Delegates to ``click.unstyle`` (``click==8.3.2`` in ``requirements.txt``), a
+faithful strip: it removes ANSI CSI colour / cursor / erase codes while
+preserving everything else — trailing newlines, tabs, spacing — so command
+output isn't silently mangled. (``rich.text.Text.from_ansi`` was rejected: it
+line-normalizes and drops trailing newlines.)
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def strip_ansi(text: str) -> str:
+ """Return ``text`` with all ANSI escape sequences removed.
+
+ Empty / falsy input is returned unchanged. Pure-text input is byte-for-byte
+ unaffected, so this is safe to call unconditionally on any captured stream
+ line.
+ """
+ if not text:
+ return text
+ return click.unstyle(text)
+
+
+__all__ = ["strip_ansi"]
diff --git a/server/nodes/filesystem/shell/__init__.py b/server/nodes/filesystem/shell/__init__.py
index 875b988f..7c343880 100644
--- a/server/nodes/filesystem/shell/__init__.py
+++ b/server/nodes/filesystem/shell/__init__.py
@@ -7,6 +7,7 @@ from typing import Any, Optional
from pydantic import BaseModel, ConfigDict, Field
+from core.ansi import strip_ansi
from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
@@ -93,6 +94,10 @@ class ShellNode(ActionNode):
params.command,
timeout=params.timeout,
)
+ # Strip ANSI colour/cursor codes — commands like ``vite build`` / ``npm``
+ # emit them and they render as garbage ("[36m…[39m") in the Output panel.
+ clean_output = strip_ansi(result.output)
+
if result.exit_code == 124:
log.warning("[Shell] Timed out after %ds: %s", params.timeout, params.command[:100])
elif result.exit_code != 0:
@@ -100,13 +105,13 @@ class ShellNode(ActionNode):
"[Shell] Non-zero exit (%d): %s -> %s",
result.exit_code,
params.command[:100],
- result.output[:300],
+ clean_output[:300],
)
else:
- log.info("[Shell] Completed: exit=%d len=%d", result.exit_code, len(result.output))
+ log.info("[Shell] Completed: exit=%d len=%d", result.exit_code, len(clean_output))
return {
- "stdout": result.output,
+ "stdout": clean_output,
"exit_code": result.exit_code,
"truncated": result.truncated,
"command": params.command,
diff --git a/server/services/process_service.py b/server/services/process_service.py
index 04dc41cd..4254a0a2 100644
--- a/server/services/process_service.py
+++ b/server/services/process_service.py
@@ -18,6 +18,7 @@ from datetime import datetime
from pathlib import Path
from typing import Any, Awaitable, Callable, Dict, List, Optional
+from core.ansi import strip_ansi
from core.logging import get_logger
from services._supervisor.util import kill_tree
@@ -405,7 +406,10 @@ class ProcessService:
line = await stream.readline()
if not line:
break
- text = line.decode(errors="replace").rstrip()
+ # Strip ANSI colour/cursor codes so the Terminal tab, the
+ # persisted log file, and get_output() all show clean text
+ # (vite/npm/etc. emit colour codes that render as garbage).
+ text = strip_ansi(line.decode(errors="replace")).rstrip()
# Write to log file
f.write(text + "\n")
diff --git a/server/tests/conftest.py b/server/tests/conftest.py
index 0e7c61c7..734f6b41 100644
--- a/server/tests/conftest.py
+++ b/server/tests/conftest.py
@@ -97,6 +97,18 @@ _make_submodule("core", "credentials_database", {"CredentialsDatabase": MagicMoc
_make_submodule("core", "config", {"Settings": MagicMock})
_make_submodule("core", "cache", {"CacheService": MagicMock})
+# core.ansi — load the REAL module from file (it only depends on ``rich``, no
+# heavy core deps), so the stubbed-core environment still exposes the genuine
+# ``strip_ansi`` that process_service / the shell node import at module load.
+# File-load (not a lambda) keeps tests exercising the actual implementation.
+import importlib.util as _importlib_util # noqa: E402
+
+_ansi_spec = _importlib_util.spec_from_file_location("core.ansi", SERVER_DIR / "core" / "ansi.py")
+_ansi_mod = _importlib_util.module_from_spec(_ansi_spec)
+sys.modules["core.ansi"] = _ansi_mod
+_ansi_spec.loader.exec_module(_ansi_mod)
+setattr(_core_pkg, "ansi", _ansi_mod)
+
# core.paths — central path resolution. Stub the public surface with
# tmpdir-rooted Paths so plugin module imports don't trip over the
# real ``Path.home()`` lookup during test collection. Tests that
diff --git a/server/tests/test_ansi.py b/server/tests/test_ansi.py
new file mode 100644
index 00000000..aa15b167
--- /dev/null
+++ b/server/tests/test_ansi.py
@@ -0,0 +1,39 @@
+"""strip_ansi — terminal-output ANSI cleaning (core/ansi.py)."""
+
+from __future__ import annotations
+
+from core.ansi import strip_ansi
+
+
+def test_strips_sgr_colour_codes():
+ assert strip_ansi("\x1b[36mvite v7.3.3\x1b[39m") == "vite v7.3.3"
+
+
+def test_strips_real_vite_build_line():
+ # The exact shape from a `vite build` stdout (CSI colour + reset codes).
+ raw = (
+ "\x1b[36mvite v7.3.3 \x1b[32mbuilding client environment for "
+ "production...\x1b[36m\x1b[39m transforming... \x1b[32m✓\x1b[39m "
+ "8 modules transformed."
+ )
+ cleaned = strip_ansi(raw)
+ assert "\x1b" not in cleaned
+ assert "[36m" not in cleaned and "[39m" not in cleaned
+ assert cleaned == (
+ "vite v7.3.3 building client environment for production... "
+ "transforming... ✓ 8 modules transformed."
+ )
+
+
+def test_plain_text_unchanged():
+ assert strip_ansi("no escape codes here") == "no escape codes here"
+
+
+def test_empty_and_falsy_passthrough():
+ assert strip_ansi("") == ""
+ assert strip_ansi(None) is None # type: ignore[arg-type]
+
+
+def test_strips_cursor_and_erase_sequences():
+ # Not just colour: cursor-move (H) + erase-line (K) CSI sequences too.
+ assert strip_ansi("\x1b[2K\x1b[1Gprogress") == "progress"