Repository navigation
v1.8.2 — Live browser viewer for the Teaching Colony
What's new in v1.8.2
A browser-based live visualisation of a running Teaching Colony session. A reader running python -m examples.teaching_colony.chat --view sees the colony's agents laid out by layer, watches dispatches animate between them, and sees Teacher's answer appear in a bottom panel while the token budget gauge ticks up in real time.
The shape
The visual layout was brainstormed in a merged-wireframe session before any code was written. User node on the left, L1 Governance band (Registry, Chronicler, Equilibrium), L2 Immune band (Sentinel), L3 Domain band (Librarian, Teacher), Knowledge Base cells at the bottom with real topics + dashed v1.9 slots, explicit "INTERNET (v1.9)" placeholder node for fetch_url, rolling event log on the right, token budget gauge on top, streaming answer panel at the bottom.
The underlying event stream is state/events.jsonl — exactly what v1.8.0's adapter already writes, plus two new adapter events (dispatch.start and kb.read) that give the viewer cleaner animation hooks.
How to use it
cd examples/teaching_colony
# Offline, no cost — watch the mechanism animate
python -m examples.teaching_colony.chat --mock --view
# Live mode — real Claude, real tokens, real budget gauge
export ANTHROPIC_API_KEY=...
python -m examples.teaching_colony.chat --view
# Custom port, don't auto-open browser
python -m examples.teaching_colony.chat --view --view-port 9000 --no-openThen type ask what do you know about beekeeping at the terminal. Watch Teacher's ring pulse in the browser, see the KB beekeeping cell light up, watch the answer stream into the bottom panel, see the token budget tick up.
Architecture
viewer.py(~320 lines) — pure-stdlib asyncio HTTP server. Two endpoints:/serves the HTML,/eventsis a Server-Sent Events stream. Binds to127.0.0.1only (contract-checked). Tailsstate/events.jsonlvia a 100ms polling task. Sends aninitial_stateevent on connect, replays the existing log, then streams live events.viewer.html(~500 lines) — single-file HTML with embedded CSS, vanilla JS, and SVG. No build step. No external CDN.EventSource('/events')subscribes and handles every event type with a distinct CSS animation. Auto-reconnects with a 2s backoff if the server restarts.chat.py --view / --view-port / --no-open— three new flags. The viewer starts as an asyncio task alongside the existing REPL loop and shuts down cleanly on REPL exit.- Two new adapter events —
dispatch.start(paired with the existingdispatch.complete) andkb.read(emitted on every KB query with the matched topic names). Both substrates emit them identically.
Security hygiene
- Binds to
127.0.0.1only. Never0.0.0.0. Contract-checked at startup, test-covered. - No POST support. Every non-GET request returns 405.
textContent, neverinnerHTML. Every field from the event stream is set viatextContentorcreateElementNS + appendChild. A test explicitly asserts.innerHTMLdoes not appear anywhere inviewer.html. This is preemptive XSS hygiene for v1.9 — when research walks start feeding fetched web content through the event stream, the same JS code will handle it without risk.- No
eval, noFunction(), no dynamic script injection. Events are strictly data. - Event log entries capped at 500 chars before rendering.
What's deferred
- Browser input. The user still types commands in the terminal. Bidirectional browser-to-REPL control is v1.8.3 or v2.0.
- Research walk animation. The Internet node is a dashed placeholder labelled "v1.9" and "not wired in v1.8.2". When v1.9 lands, the viewer picks up the new events without any layout change.
- Past-session replay, mobile layout, streaming token counter. All v2.0.
Tests
15 new tests, all in mock mode, no API key required. Full suite now 91 passed, 3 deselected (live Claude tests), 2 xfailed (unchanged Managed Agents live-mode stubs). Full suite runs in 2.24 seconds.
tests/test_viewer_server.py— 8 tests covering every endpoint, the initial-state replay, live tailing, and security contractstests/test_viewer_html.py— 6 structural checks (required SVG ids, agent nodes, JS function names,.innerHTMLabsence, EventSource target, v1.9 labelling)tests/test_chat_view_flag.py— end-to-end subprocess smoke test that runschat.py --viewand hits the URL
Why v1.8.2 and not v1.9 first
v1.8.0 was "live Claude dispatch". v1.8.1 was "§7 enforcement hole closed after review". v1.8.2 is "a reader can now see the mechanism work". Each increment is its own commit-test-tag-release cycle. v1.9 still owns research walks — but when research walks ship, the viewer is already there to animate them.
The merged-wireframe brainstorm with the visual companion produced a shape that was approved before a single line of code was written. That's why the implementation was a straight-line sequence of seven files, two small adapter edits, and a handful of tests — no mid-implementation redesigns, no "wait that doesn't look right" moments, no drift between what was agreed and what shipped.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.2). https://github.com/DavidROliverBA/agent-colony-pattern