Skip to content

v1.8.2 — Live browser viewer for the Teaching Colony

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 15 Apr 06:21
· 3 commits to main since this release

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

Then 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, /events is a Server-Sent Events stream. Binds to 127.0.0.1 only (contract-checked). Tails state/events.jsonl via a 100ms polling task. Sends an initial_state event 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 existing dispatch.complete) and kb.read (emitted on every KB query with the matched topic names). Both substrates emit them identically.

Security hygiene

  1. Binds to 127.0.0.1 only. Never 0.0.0.0. Contract-checked at startup, test-covered.
  2. No POST support. Every non-GET request returns 405.
  3. textContent, never innerHTML. Every field from the event stream is set via textContent or createElementNS + appendChild. A test explicitly asserts .innerHTML does not appear anywhere in viewer.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.
  4. No eval, no Function(), no dynamic script injection. Events are strictly data.
  5. 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 contracts
  • tests/test_viewer_html.py — 6 structural checks (required SVG ids, agent nodes, JS function names, .innerHTML absence, EventSource target, v1.9 labelling)
  • tests/test_chat_view_flag.py — end-to-end subprocess smoke test that runs chat.py --view and 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