feat: add reusable terminal helix visualizer module

[jkbennitt]

Summary

• Adds src/felix_agent_sdk/visualization/ module with HelixVisualizer for real-time ASCII rendering of agents progressing down the helix
• Extracts and generalizes the 2D projection, ANSI rendering, and canvas patterns from examples/05_deep_research_live/ into a reusable SDK component
• State-based API: register_agent() → update() → render() with live() context manager for terminal cleanup

What it does

Renders a terminal-based helix showing agent positions, phase boundaries (exploration/analysis/synthesis), animated backbone, per-agent sidebar with confidence bars, and team confidence footer. Works on Windows (pure ANSI, no curses). Respects NO_COLOR/FORCE_COLOR env vars.

Files

File	Lines	Purpose
visualization/__init__.py	18	Exports HelixVisualizer, AgentDisplayState
visualization/terminal.py	101	ANSI primitives: colors, cursor, progress bars
visualization/helix_visualizer.py	485	Core visualizer: canvas, projection, sidebar, animation
tests/unit/test_helix_visualizer.py	206	23 tests covering registration, rendering, NO_COLOR, dimensions
__init__.py	+3	Added HelixVisualizer to top-level exports

Usage

from felix_agent_sdk import HelixVisualizer
from felix_agent_sdk.core.helix import HelixConfig

viz = HelixVisualizer(HelixConfig.default().to_geometry())
viz.register_agent("resource_mgr", label="RM", color="green")
viz.update("resource_mgr", progress=0.3, confidence=0.82)
viz.render(tick=47, day=12)

Test plan

• pytest tests/unit/test_helix_visualizer.py -v — 23 tests pass
• pytest tests/ -v — 686 total pass, no regressions
• ruff check src/felix_agent_sdk/visualization/ — clean
• Manual smoke test with multiple agents rendering in a loop
• @CalebisGross review

🤖 Generated with Claude Code

[CalebisGross]

Ran the gates locally -- couple small things before merging:

• tests/unit/test_helix_visualizer.py has an unused import os (ruff F401)
• helix_visualizer.py and the test file need a ruff format pass

mypy is clean, all 23 tests pass. Should be a quick fix.

[jkbennitt]

Fixed both items — removed the unused import os and ran ruff format on both files. 23 tests pass, lint clean. Ready for re-review. (2680e73)

[CalebisGross]

Gates pass, code is clean. Ship it.

[CalebisGross]

Nit: _COLOR_MAP in helix_visualizer.py duplicates the ANSI constants from terminal.py. Could consolidate into a single lookup, but not a big deal.

[jkbennitt]

Consolidated _COLOR_MAP into terminal.py as COLOR_MAP, built from the existing ANSI constants instead of re-hardcoding them. (65f5965)

[CalebisGross]

Nice, that's the good stuff.

[jkbennitt]

Updated — visualizer now integrates with all four dev/phase-2 features:

• Events: attach_event_bus() auto-registers agents on AGENT_SPAWNED, updates on AGENT_POSITION_UPDATED, marks DONE/FAILED
• Streaming: VisualizerStreamHandler shows live token count in the sidebar
• Spawning: set_monitor() adds confidence trend (↑↓→) and spawn recommendation to footer
• CLI: felix run config.yaml --visualize for live helix during workflows

Rebased on latest dev/phase-2 (includes CLI, dynamic spawning, streaming, events). 823 tests pass, 31 visualizer-specific. (94b4189)