Skip to content

v1.8.3 — Two view fallbacks for locked-down environments

Latest

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 15 Apr 07:57
· 2 commits to main since this release

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-native

Opens 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-file

Writes 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 by static_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 task
  • examples/teaching_colony/viewer_native.py (~240 lines) — pywebview wrapper, lazy import with helpful error, background event-pump thread
  • examples/teaching_colony/viewer.html — data-view-mode switch, window.pushColonyEvent global, initViewMode() dispatcher, META_REFRESH_PLACEHOLDER hook
  • examples/teaching_colony/chat.py — --view-native, --view-file flags; mutex check; fail-fast pywebview availability check
  • examples/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 helpers
    • tests/test_viewer_html_mode_switch.py (7) — structural checks on the three-branch dispatcher
    • tests/test_chat_view_file_flag.py (3) — subprocess end-to-end: --view-file writes the file, mutex rejects combined flags, --view-native without 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

  1. 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-file is the guaranteed fallback.
  2. Managed Chrome might disable file://. A few corporate Chrome policies ban file:// 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