Repository navigation
What's new in v1.8.3
v1.8.2 shipped a live browser viewer that talks to a local HTTP server. On some corporate machines — the author's BA laptop among them — the browser refuses to connect to 127.0.0.1:8765 even when the server is listening. Managed Chrome, Zscaler proxies, and certain EDR configurations block the connection at the network stack, and the browser shows ERR_CONNECTION_REFUSED.
v1.8.3 adds two escape hatches. Same wireframe. Same viewer.html. Three data paths between the REPL and the screen.
The three modes
| Flag | How it renders | Pros | Cons |
|---|---|---|---|
--view (v1.8.2) |
Browser ↔ localhost HTTP/SSE | Richest UX, live animation, prompt-cache hit visible, true streaming | Blocked by some endpoint security |
--view-native (v1.8.3) |
Native WebKit window via pywebview |
No HTTP, no browser, no proxy; real animations and JS bridge | Requires pip install pywebview |
--view-file (v1.8.3) |
Static HTML file auto-refreshed every 2s | Zero new deps, works via file:// everywhere |
No animation between reloads |
All three are mutually exclusive. Pick the one that works in your environment; the README has a decision flow.
--view-native — pywebview native window
pip install pywebview
python -m examples.teaching_colony.chat --view-nativeOpens a native macOS WebKit window. Python pushes events into the window's JavaScript context via window.evaluate_js(...) — no HTTP server involved. The window is rendered by the OS-level WebKit.framework (reached through pyobjc-framework-WebKit), which corporate Chrome policies don't govern. If pywebview is not installed, chat.py fails with a clean install hint before even printing the banner.
Constraint: pywebview.start() requires the main thread on macOS, so the REPL runs in a background thread. Closing the window shuts the REPL down gracefully.
--view-file — static HTML with auto-refresh
python -m examples.teaching_colony.chat --view-fileWrites state/live-view.html to disk. The file contains the whole event stream embedded as a JavaScript constant, plus a <meta http-equiv="refresh" content="2"> tag. Your browser opens the file via file:// — zero network requests, no proxy involvement, works on any machine. chat.py rewrites the file every 500ms in the background so each refresh catches up to the latest events.
Trade-off: each page reload is a full re-render, so animations between reloads are lost. This is the price of the file:// approach — any live-streaming approach needs HTTP, which is exactly what we're avoiding.
How it's implemented
One viewer.html drives all three modes via a data-view-mode attribute:
<body data-view-mode="sse"> <!-- v1.8.2 default -->
<body data-view-mode="native"> <!-- pywebview mode, set by viewer_native.py -->
<body data-view-mode="static"> <!-- file mode, set by static_view.py -->The JavaScript checks data-view-mode on load and dispatches to the right init path:
- SSE mode opens
EventSource('/events')as before (v1.8.2 behaviour unchanged) - Native mode shows a "waiting for first dispatch" banner and waits for Python to call
window.pushColonyEvent(evt)directly - Static mode reads
window.EMBEDDED_EVENTS(injected bystatic_view.py) and replays each event through the same handler
All three feed events into a unified window.pushColonyEvent hook, so the actual rendering code (SVG updates, CSS animations, event log, budget gauge, answer panel) is identical across modes. Zero duplication.
Shipped
examples/teaching_colony/static_view.py(~230 lines) — template rewriter, snapshot builder/writer, periodic asyncio taskexamples/teaching_colony/viewer_native.py(~240 lines) — pywebview wrapper, lazy import with helpful error, background event-pump threadexamples/teaching_colony/viewer.html— data-view-mode switch,window.pushColonyEventglobal,initViewMode()dispatcher,META_REFRESH_PLACEHOLDERhookexamples/teaching_colony/chat.py—--view-native,--view-fileflags; mutex check; fail-fast pywebview availability checkexamples/teaching_colony/README.md— "Three ways to view the colony" section with comparison table, per-mode subsections, decision flow- 22 new tests:
tests/test_static_view.py(12) — build/write snapshot, event reading helperstests/test_viewer_html_mode_switch.py(7) — structural checks on the three-branch dispatchertests/test_chat_view_file_flag.py(3) — subprocess end-to-end:--view-filewrites the file, mutex rejects combined flags,--view-nativewithout pywebview fails cleanly
Test results
113 passed, 3 deselected (live), 2 xfailed in 2.62s
22 more tests than v1.8.2. Full suite still runs in under three seconds.
Dependency policy
v1.8.3 keeps v1.8.x's "zero new required dependencies" promise. --view and --view-file work with pure stdlib. --view-native requires pywebview, which is an optional runtime dependency — not in requirements.txt, imported lazily, fails with a one-line pip install pywebview hint if missing.
Why v1.8.3 and not waiting for v1.9
The corporate endpoint security block is real and immediate for the author. Waiting for v1.9 to ship research walks would mean several more days of not being able to use v1.8.2's viewer on the machine where it's most needed. v1.8.3 is a surgical patch — two new flags, three new files, two adapters unchanged. v1.9 still owns research walks; they'll animate through whichever view mode the user has chosen.
Known residual risks
- pywebview might still be blocked. Some EDR products hook process creation and deny apps that dynamically load
pyobjc-framework-WebKit. Rare but possible. If it happens,--view-fileis the guaranteed fallback. - Managed Chrome might disable
file://. A few corporate Chrome policies banfile://URLs entirely. If yours does, Safari or Firefox on the same machine usually don't.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.3). https://github.com/DavidROliverBA/agent-colony-pattern