Repository navigation
Releases
v1.8.3 — Two view fallbacks for locked-down environments
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
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
v1.8.1 — DSL dual-key bypass closed
What's new in v1.8.1
A targeted fix for a latent bypass in the §7 Comprehension Contract enforcement, flagged by the external review of v1.8.0.
The bug
Before v1.8.1, _apply_changes had a backwards-compat fallthrough that silently deep-merged any unknown top-level key as a literal YAML patch. A caller passing the legacy capability_add name (singular — the exact v1.6.x bug key) bypassed the DSL entirely:
_change_action_classinferredmirror_patch(notmirror_capability_add)ACTION_BLAST_RADIUS[mirror_patch]is not in the table → defaultLocal- Blast-radius-ceiling check passed trivially
- Forbidden-list keyword match missed (
"add new teaching"doesn't appear in"Patch mirror with keys: ['capability_add']") _apply_changesdeep-mergedcapability_addas a top-level YAML key — the exact v1.6.x failure mode the DSL was meant to kill
The review's exact words: "the Comprehension Contract enforcement can still be fully bypassed by a caller using the legacy key name."
The fix
Three lines, as the reviewer suggested. Both substrates now reject any top-level key not in {add_capability, remove_capability, patch} up front:
KNOWN_DSL_KEYS = {"add_capability", "remove_capability", "patch"}
for key in changes:
if key not in KNOWN_DSL_KEYS:
raise ValueError(f"Unknown change DSL key: {key!r}. …")Unknown keys get a "did you mean …" hint in the exception message for ergonomics, but they raise. No fallthrough.
Four new regression tests
In examples/teaching_colony/tests/test_contract_enforcement.py:
test_legacy_capability_add_key_is_rejected— provokes the exact v1.6.x bypasstest_random_unknown_dsl_key_is_rejected— generalises to any non-DSL keytest_patch_key_still_works_for_legitimate_literal_updates— confirms the explicitpatchescape hatch survivestest_mixed_dsl_and_legacy_key_rejects_entire_change— atomic gate: a mix of valid and invalid keys rejects the whole change before any mutation
Four existing tests migrated
Tests that used the pre-DSL nested-dict form {"capabilities": {"capabilities": [...]}} now use the semantic add_capability DSL key instead. This was necessary because the nested-dict form relied on the (now-removed) fallthrough.
Test results
76 passed, 3 deselected (live), 2 xfailed
Four more tests than v1.8.0. Every pre-existing mock-mode test still green.
Why v1.8.1 and not fold into v1.9
The review landed after v1.8.0 shipped. Folding this into v1.9 would mean releasing v1.8 with a known governance hole for however long v1.9 takes. That repeats the v1.6.x failure mode the §7 hardening was meant to close. Tiny targeted patch, ship now, keep v1.9 a clean increment.
The §7 enforcement story — final form
After v1.7.0 the Comprehension Contract had four real checks (co-signer presence, blast-radius-ceiling, forbidden-list, policy freshness) implemented in update_mirror. The review's finding was that these checks ran on the wrong classification when the caller used an unknown top-level key, because the fallthrough turned the change into a literal patch. v1.8.1 removes the fallthrough. The §7 enforcement story no longer has a qualifier.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.1). https://github.com/DavidROliverBA/agent-colony-pattern
v1.8.0 — Teaching Colony runs on real Claude
What's new in v1.8.0
First release where the Teaching Colony actually runs on a real language model. v1.8.0 adds an interactive REPL and fills in the Claude Code adapter's live-mode dispatch path with real Anthropic API calls, prompt caching, and model tiering. A reader can now type ask what do you know about beekeeping at a colony prompt and receive a real Claude answer grounded in the seeded primer — not a canned mock string.
This is the first release of the Agent Colony pattern that costs money to use. The README section explains the envelope in detail: roughly $2-5 for a full 500,000-token session with the recommended Sonnet/Haiku model mix, after prompt caching kicks in.
Why v1.8 as its own increment
v1.6.0 shipped a 4,300-line artefact where the headline claim was false on the happy path (see v1.7.0 release notes). That review is still fresh. v1.8.0 ships the live-mode dispatch path on its own — and nothing else — so it can be verified end-to-end against a real model before v1.9 layers research walks on top. v2.0 will add the full command set, session persistence, and cost enforcement. Each increment gets its own commit-test-tag-release cycle.
What v1.8.0 adds
- Interactive REPL —
examples/teaching_colony/chat.py. asyncio-based. Commands:ask,help,quit. Forward-looking v1.9+ commands (research,status,cancel,knows,capabilities) route helpfully to "coming in v1.9+" messages rather than tracebacks. - Live-mode
dispatch_agentin the Claude Code substrate:- Prompt caching —
cache_control: ephemeralon the Mirror system prompt. Repeat dispatches of the same agent within 5 minutes pay ~10% of the system-prompt cost. The REPL's budget display shows cache-read tokens as a separate counter so you can see it work. - Model tiering — Sonnet for Teacher and Librarian (real pedagogical work); Haiku for Registry, Chronicler, Equilibrium, Sentinel (small structured decisions).
- Prose-vs-JSON prompt discipline — Teacher and Librarian get pedagogical prompts; the four supervisory agents get JSON-strict prompts with explicit schemas and a one-retry fallback for malformed responses.
- Prompt caching —
- Session budget —
examples/teaching_colony/colony/logic/budget.py.Budgetclass tracking all four Anthropic usage counters.TEACHING_COLONY_TOKEN_BUDGETenv var, default 500,000, safe fallback on invalid values. 80% warning, 100% hard stop for new dispatches. - Three new test modules — 36 new tests covering the Budget class (27), REPL smoke in mock mode (9), and gated live-Claude dispatch (3). The live tests require
ANTHROPIC_API_KEYand run withpytest -m live; they prove that prompt caching actually hits on the second dispatch (cache_read_input_tokens > 0).
Test results
72 passed, 3 deselected (live tests), 2 xfailed
Every v1.7.0 mock-mode test still passes. The 2 xfails are unchanged — live-mode Managed Agents dispatch_agent and update_mirror, still deferred until research-preview allowlist.
How to try it
cd examples/teaching_colony
pip install -r requirements.txt
# Offline, no cost, good for seeing the mechanics
python -m examples.teaching_colony.chat --mock
# Live mode — real Claude, real tokens, ~$0.15 for ~30 questions
export ANTHROPIC_API_KEY=...
python -m examples.teaching_colony.chat
# Tighter budget for cost discipline
TEACHING_COLONY_TOKEN_BUDGET=50000 python -m examples.teaching_colony.chatKnown gaps after v1.8.0
- No research walks yet.
research,status,cancel,knows,capabilitiesare all v1.9+. - No tool use.
fetch_url,extract_links,score_linksare v1.9+. - No background concurrency. Research walks will run concurrently in v1.9; v1.8 has one synchronous dispatch per
ask. - No capability graduation yet. v1.9 wires Librarian's coverage check to the existing §7 Comprehension Contract path.
- Retrieval is single-shot keyword match, not real RAG. Fine while the KB has one entry; replaced in v2.0 when the KB has dozens.
- REPL dispatches only to Teacher.
ask sentinel co-sign thiskind of syntax is v2.0. - Tokens display is post-dispatch, not streaming. A streaming token counter is v2.0 polish.
- Managed Agents live-mode
dispatch_agentandupdate_mirrorstill raise NotImplementedError (2 xfails, unchanged from v1.7.0).
Roadmap updated
The repo roadmap now reads:
| Version | Status | Focus |
|---|---|---|
| v1.8.0 | ✅ released 2026-04-14 | Live-mode dispatch, prompt caching, REPL foundation |
| v1.9.0 | planned | Research walks with hop budget, tool use, G3 graduation |
| v2.0.0 | planned | Full interactive Teaching Colony — reference implementation |
| v2.1+ | planned | Live-mode Managed Agents, Newcomer diagrams, peer feedback |
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.8.0). https://github.com/DavidROliverBA/agent-colony-pattern
v1.7.0 — Honest Teaching Colony (response to external review)
What's new in v1.7.0
v1.7.0 is a correctness release for the Teaching Colony example, responding to an external review that found six concrete bugs in v1.6.x. The review described v1.6.x as "a 4,300-line artefact whose headline demonstration doesn't hold up under a single run-and-inspect". Every finding is now addressed. The review is preserved verbatim at examples/teaching_colony/docs/review-2026-04-14.md as the before-state that v1.7.0 corrects.
What was broken in v1.6.x
- The mock dispatch path was dead code — driver and adapter disagreed on argument shape, so both Teacher dispatches fell through to
{ok: True}. The README's headline claim was false. - The capability landed in the wrong place in the Mirror — deep-merge wrote a new top-level YAML key instead of appending to
capabilities.capabilities[]. - The Comprehension Contract was not enforced —
update_mirrordid none of the checkssubstrate-contract.mdpromised. - The event stream was duplicated — driver and adapter emitted the same logical actions with different names.
- Mirror writes polluted git-tracked files — every run left
colony/mirrors/teacher-agent.yamlmodified. - The classifier accepted caller-supplied
blast_radiusoverrides — a confused caller could downgrade a Colony-wide action to Local.
What v1.7.0 changes (three batches)
Batch 1 — correctness (the headline claim must become true)
- Fix 6: classifier gate — action classes in the table are authoritative; caller override only applies to unknown classes.
- Fix 2: semantic change DSL for
update_mirror—add_capability,remove_capability,patchas explicit instructions. - Fix 1: wire the mock dispatch path — adapter normalises agent id and keys on the actual input shape the driver sends. Canned answers now contain the words "worker" (beekeeping) and "Mirror" (Agent Colony pattern) — exactly what the new walkthrough test asserts against.
Batch 2 — the Comprehension Contract actually bites
- Fix 3:
update_mirrorperforms six checks before writing — co-signer presence, classifier invocation, blast-radius-ceiling, forbidden-list, co-signer policy freshness, hash/merge/write. Each check raises a specificContractViolationsubclass. - New test module:
tests/test_contract_enforcement.py— five tests that provoke each check in turn. The first time the §7 Comprehension Contract has ever done real work in running code.
Batch 3 — design cleanup
- Fix 4: single event ownership — adapters own adapter-internal events (
kb.written,mirror.updated,cosign.granted,dispatch.complete); driver stops emitting duplicates. Both substrates now emit identical event sequences in mock mode. - Fix 5: Mirror writes land in
state/mirrors/overlay.colony/mirrors/is now read-only at rest. Running the example no longer pollutes git-tracked files. - Corpus README explaining why the corpus is a snapshot (not a symlink) and how to refresh it.
- Substrate contract text fixes — the enforcement paragraph is rewritten to name the six checks; the change DSL gets its own section; the aspirational "every substrate we tried" claim about
read_eventis replaced with an honest statement.
The v1.7.0 testing innovation
tests/test_walkthrough.py runs the lifecycle driver end-to-end and asserts seven observable properties of state/events.jsonl and the Teacher Mirror:
- Teacher's beekeeping answer contains "worker" (proves the canned branch fired)
- Teacher's Agent Colony answer contains "Mirror" (proves the new capability is used)
- Teacher's Mirror contains both capabilities under
capabilities.capabilities[] - No floating
capability_addkey at the root of the Mirror - Classification event with
review_regime: Peer Review cosign.grantedevent withgranted: Truemirror.updatedevent with differing pre/post state hashes
This test is the mechanism that prevents tests-vs-demo drift in future releases. If a future change breaks the walkthrough, this test fails — even if every other adapter test passes.
Portability parity: v1.6.x skips are now v1.7.0 passes
The two tests that were marked skip in v1.6.x — test_event_log_types_match and test_teacher_mirror_final_state_matches — now pass. Both substrates produce byte-identical event sequences and Mirror final states in mock mode. The 42-vs-22 event-count gap from v1.6.1's honest note is gone.
Test results
36 passed, 2 xfailed
The 2 xfails are live-mode dispatch_agent and update_mirror for the Managed Agents adapter — these require the research-preview allowlist and real API calls. Mock-mode portability parity is fully achieved.
Known gaps after v1.7.0
- Live-mode Managed Agents
dispatch_agentandupdate_mirrorstill raiseNotImplementedError. Target: v1.8+ when research-preview access is available. - v1.7.0 ships with
write_kbandco_signas colony-policy operations that work in both mock and live mode (they don't need a Managed Agents API call — writes go to local files; co-sign is a Mirror policy lookup). This is a scope refinement: these two operations were previously xfailed but are now correctly not substrate-dependent.
Philosophically
The review's closing line: "The cure is to apply the same honesty to the example that the thesis now applies to itself." v1.7.0 is that cure — the example's code now does what its README promises, and when it doesn't, test_walkthrough.py notices.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.7.0). https://github.com/DavidROliverBA/agent-colony-pattern
v1.6.1 — Teaching Colony design artefacts + usage walkthrough
What's new in v1.6.1
Docs-only patch for the Teaching Colony example. Fixes two gaps a first-time reader would notice in v1.6.0:
Design spec and implementation plan are now in the public repo
Both documents lived only in the author's vault at v1.6.0. They are now at examples/teaching_colony/docs/ with provenance headers:
- design-spec.md — the scope, motivation, substrate contract, agent composition, lifecycle, and deferrals
- implementation-plan.md — the five-sub-agent parallel execution strategy that actually built v1.6.0, including coordination rules, write-scope boundaries, and the research risk
These are the Architect-lens artefacts for the example. Both substrate READMEs now link to them from their "Design context" line.
The README now has a three-scenario usage walkthrough
v1.6.0 had the commands but not a guided path. The new examples/teaching_colony/README.md walks a reader through three progressive runs:
- Run 1 — see the whole lifecycle on Claude Code. Install, run, read the summary table, open
state/events.jsonl, inspect the updated Mirror, check the graduation checklist. - Run 2 — reset and re-run to verify determinism. Confirm the same mock-mode colony produces the same observable events on repeated runs.
- Run 3 — same colony on the Managed Agents substrate. See the portability claim concretely — same six Mirrors, same classifier, same observable graduation, different adapter.
Each scenario states what to run, what to expect on stdout, where to look in state/, and how to verify the graduation happened.
Honest about the event-count gap
The walkthrough does not pretend the two substrates produce identical output at v1.6.0. Claude Code emits ~42 events; Managed Agents emits ~22. The README explains why (mock update_mirror and write_kb are no-ops on Managed Agents, dispatch.complete events not emitted), points at gaps.md for the documented reason, and confirms the portability parity tests remain in skip state for v1.6.0. Full parity is a v1.7+ deliverable.
No code changes
- Adapters unchanged
- Colony definition unchanged
- Tests unchanged (26 passed, 2 skipped, 4 xfailed — identical to v1.6.0)
Known follow-up flagged for v1.7+
The Claude Code adapter writes Mirror updates back to colony/mirrors/ which is git-tracked. Real runs pollute the committed example. This was caught during v1.6.1 verification when a walkthrough test-run left graduation entries in teacher-agent.yaml. The fix (move Mirror writes to state/ or make the adapter copy-on-write) is targeted for v1.7+.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.6.1). https://github.com/DavidROliverBA/agent-colony-pattern
v1.6.0 — Teaching Colony (first substrate-portable example)
What's new in v1.6.0
A six-agent Agent Colony that teaches the pattern, running identically on two substrates.
Until this release the pattern had no artefact showing it actually running on real agent infrastructure. v1.6.0 is the first. A six-agent Teaching Colony — Registry, Chronicler, Equilibrium, Sentinel, Librarian, Teacher — lives in examples/teaching_colony/ and runs on two substrates behind a common SubstrateContract ABC. The demonstration is the portability.
What this exercises for the first time in running code
- Principle 2 — Identity over implementation. The six Agent Mirrors are substrate-independent. The same YAML files are loaded by both adapters.
- Principle 4 — Longevity by design. The colony can be lifted from one substrate to the other without rewriting Mirrors, logic, or event memory.
- The Comprehension Contract (§7). Until now §7 was prose. v1.6.0 makes it fire: Librarian detects KB coverage crossing a threshold, proposes Teacher acquire
teach_agent_colony_pattern, the Structural Classifier fires with the §7.4 review regime formula (Novel action class → Peer Review short-circuit), Sentinel co-signs, Teacher's Mirror is updated with an append-only audit entry including pre/post state hashes. - Principle 7 — Accessibility through abstraction. The colony's purpose is to teach, using beekeeping as its running pedagogical example. The purpose realises the principle.
The substrate contract
Eight operations every substrate must implement. This is what L4 owes L1–L3:
class SubstrateContract(ABC):
def dispatch_agent(self, agent_id, input) -> dict
def read_mirror(self, agent_id) -> Mirror
def update_mirror(self, agent_id, changes, co_signer) -> AuditEntry
def record_event(self, event) -> None
def read_kb(self, query) -> list[Document]
def write_kb(self, topic, content, provenance) -> None
def co_sign(self, action_class, actor, co_signer) -> Signature
def classify_action(self, action, context) -> ClassificationTwo substrates
- Claude Code (
substrates/claude_code/) — orchestrates the colony via the Anthropic Python SDK. Full 8-operation implementation, working in mock mode offline, ready for real Claude API calls. 8 unit/lifecycle tests passing. - Managed Agents API (
substrates/managed_agents/) — scaffolding adapter with mock mode fully working. Live-mode operations are gated behindNotImplementedErrorpending v1.7+ completion. Ships withapi-research.md(first honest adequacy report of a real substrate against the Agent Colony contract) andgaps.md(honest v1.6.0 status).
Both substrates run the same 22-event lifecycle against the same colony definition and produce the same observable graduation.
How to run
cd examples/teaching_colony
python run.py --substrate=claude-code --mock
python run.py --substrate=managed-agents --mockBoth commands complete the lifecycle, produce a summary table, and leave a diffable event log plus Mirror updates in state/.
Test results
26 passed, 2 skipped, 4 xfailed
The 2 skips are the event-log-parity and Mirror-final-state-parity assertions, deliberately skipped in v1.6.0 with reasons pointing at gaps.md. The 4 xfails are Managed Agents live-mode operations gated for v1.7+.
Known gap
The Managed Agents substrate adapter ships with mock-mode fully working and live-mode operations gated. The mock update_mirror and write_kb are currently no-ops in the Managed Agents adapter, which is why the full event-sequence and Mirror final-state parity tests skip. Live-mode completion is targeted for v1.7+. See examples/teaching_colony/substrates/managed_agents/gaps.md for the honest adequacy report.
Status
The pattern remains practically untested at production scale — no full LLM-backed reference implementation at colony size exists yet. v1.6.0 is the first time the contract has been implemented twice and shown to work in mock mode. v2.0 remains the target for empirical threshold calibration and full production validation.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.6.0). https://github.com/DavidROliverBA/agent-colony-pattern
v1.5.0 — Accessibility Through Abstraction
What's new in v1.5.0
A seventh core principle — Accessibility through abstraction — and the audience-lens model as its canonical realisation.
Most people understand what a beehive is and what the queen bee does, but will never understand the processes, jobs, and roles all the bees perform unless they become beekeepers. The same must be true of an Agent Colony. Most audiences need a metaphor and an outcome, not a mechanism. Forcing them to read the specification to benefit from the pattern was a violation of a principle that had not yet been named. v1.5.0 names it.
Principle 7 — Accessibility through abstraction
The colony must be understandable at every audience's depth, no deeper. Complexity is an investment paid once, upfront, so that each audience sees only what it needs.
Corollary — ease is earned: the simple surface is the output of hard substrate work, not the absence of it. An implementation that is easy to use because the mechanisms aren't there is violating Principle 6 (mutual defence), not fulfilling Principle 7.
The audience-lens model
Five sequential lenses, each served by a specific artefact in this repository:
| # | Lens | Depth | Canonical artefact |
|---|---|---|---|
| 1 | Newcomer | Metaphor | It takes a village (Medium + knowledge-base/writings/) |
| 2 | Observer | Outcome | Agent outputs themselves — invisibility is the point |
| 3 | Operator | Health | Colony snapshot + equilibrium playground |
| 4 | Beekeeper | Mechanism | Agent Mirrors + hello-colony-runtime + graduation checklists |
| 5 | Architect | Substrate | Specification + thesis + schemas |
Key properties:
- Sequential by default. Natural traversal is 1→2→3→4→5. Most audiences stop at Observer.
- Re-entry is always possible. Anyone meeting an unfamiliar colony is briefly a Newcomer again, regardless of their role elsewhere.
- View, not configuration. All mechanisms — Comprehension Contract, classifier, Mirror fields, Review Regime — are present and enforced at every lens. Switching lenses changes what the audience sees, not what the colony does.
- Pacing can compress. A colony can be instantiated in an afternoon, so the traversal may take days rather than decades.
- Artefact mapping is required for conformance. Claiming Principle 7 conformance means naming which artefact serves which lens.
New in the specification
- §1 Audience Lenses — new subsection parallel to Scales of Application, describing the model, the five lenses, and their properties
- §8.5.1 anti-pattern #8 — Lens inversion — forcing low-depth audiences to read high-depth artefacts to use the colony at all
New diagram
diagrams/agent-colony-lens-traversal.svg— the five sequential lenses, their artefacts, the re-entry curve, and the view-not-configuration note in a single visual
Known gap (deferred to v1.6+)
The existing six mechanism diagrams (four-layer architecture, equilibrium system, maturity model, agent mirror, memory cycle, evolutionary context) are pitched at the Beekeeper/Architect level. By Principle 7's own test, the Newcomer and Observer lenses are under-served in diagram form — they would need companion "village-level" visual explanations that do not yet exist. This is deferred to v1.6+ rather than shipping v1.5.0 pretending the existing diagrams already serve all five lenses. Naming the gap is more honest than hiding it.
Status: The pattern remains practically untested at production scale — no full LLM-backed reference implementation exists yet. Principle 7 is additive: it describes how the colony presents itself to its audiences, not how it works. Prior v1.4.x conformance claims are not invalidated.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.5.0). https://github.com/DavidROliverBA/agent-colony-pattern
v1.4.0 — Comprehension Contract formalised as §7
What's new in v1.4.0
The Comprehension Contract is now fully formalised as §7 of the specification.
Specification: §7 Comprehension Contract (14 sub-sections)
The mechanism introduced at a high level in v1.3.0 now has a complete formal treatment across 14 sub-sections:
- §7.1 Structural Classifier — the action-time gate that must fire before any action executes
- §7.2 Quarantine and Composed Actions — path-completion timescale and action chain handling
- §7.3 Audit and Lesson Memory — days-to-weeks feedback loop closing the contract
- §7.4 Review Regime Formula — deterministic algorithm: Constitutional → Governance Council; Novel → Peer Review; Pre-registered + current + low blast → Event-line; else → REVIEW_TABLE[trust_tier][blast_radius]
- §7.5 Three Load-Bearing Properties — Completeness, Calibration, Temporal Closure
- §7.6 Classifier as Constitutional — why the classifier cannot be bypassed even for preauthorised actions
- §7.7 What the Contract Does Not Prevent — honest limits: micro-misalignment, false comprehension artefacts
- §7.8 Agent Mirror Changes — the four new Mirror fields that formalise the contract on disk
- §7.9 Relationship to Existing Mechanisms — how the Comprehension Contract interacts with the Trust Ladder, Equilibrium System, and Immune System
- §7.10 Critical Path Position — the structural vs. dynamic distinction
- §7.11 NFRs in the Mirror — colony-level and agent-specific non-functional requirements
- §7.12 Multi-Perspective Valuation — self, peer, audit, human dimensions; no single source authoritative
- §7.13 Graduation Checklist — how agents earn autonomy through demonstrated trustworthiness
- §7.14 False Comprehension Artefacts — micro-misalignment and four required defences (output-action consistency, blind audit, cross-agent blast radius verification, capability-tier heterogeneity)
Section renumbering
- Old §7 (Standards Landscape) → §8
- Old §8 (Scales of Application) → §9
- §7.5 sub-sections carry forward (now §8.5)
Two new conformance anti-patterns (§8.5.1, items 6 and 7)
- Shallow artefact production — agents that produce comprehension artefacts without genuine capability mapping
- Blast radius deflation — agents that systematically understate blast radius to avoid review
Supporting changes
thesis.md§3: Comprehension Contract subsection with Jones (2026) dark code and IndyDevDan (2026) citationsCHANGELOG.md: v1.4.0 entryCITATION.cff: version v1.4.0
Status: The pattern remains practically untested at production scale — no full LLM-backed reference implementation exists yet. The Comprehension Contract formalises the mechanism; the next step (v2.0) is empirical validation.
Previous release: v1.3.0 — Comprehension Contract Mirror fields, schema v0.2.0, hello-colony-runtime, equilibrium-playground
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.4.0). https://github.com/DavidROliverBA/agent-colony-pattern
v1.3.0 — Comprehension Contract fields + Level 1 demonstration
What's new
Comprehension Contract Mirror fields
All six hello-colony agent definitions now carry the four new Mirror sections designed in the Comprehension Contract brainstorm:
comprehension_contract:— trust tier (Observing / Sandboxed / Bounded / Self-Directed), pre-registered policies, audit rate, blast radius ceilingnfrs:— inherited colony NFRs from Constitutional Memory + agent-specific SLO commitmentsvaluation:— four-perspective scoring (self / peer / audit / human)critical_path:insiderelationships:— structural and dynamic critical path flags
Schema v0.2.0
schemas/agent-mirror-v0.2.0.json adds all four new sections. The original v0.1.json is kept intact. Pre-existing sections are now permissive (resolving schema drift accumulated since v1.1.x).
Graduation checklist
examples/hello-colony/graduation-checklists/finance-agent-v1.0-to-v1.1.yaml — the first graduation checklist. The finance agent has an overlap score of 0.24 with equilibrium-agent (watch zone). v1.1 will suppress the accreted self-monitoring capabilities. The checklist carries 3 evidence requirements, 2 approval requirements, and 3 external actions — each pre-classified with blast radius and review regime.
Hello-Colony Live Runtime
cd examples/hello-colony-runtime
pip install -r requirements.txt
python runtime.pyA deterministic Python simulation that demonstrates the pattern working as code. Loads all agent YAML files, validates against v0.2.0 schema, and runs four colony events: bootstrap (5 agents REGISTERED ✓ valid), equilibrium check (0.24 overlap flagged), security patch co-sign (CVE-2026-0441, preauthorised enum match), and graduation query.
Equilibrium Playground
open examples/equilibrium-playground/index.htmlSelf-contained HTML visualisation of the Equilibrium System. D3.js overlap matrix heatmap colour-coded by threshold zone. Threshold sliders, add/remove agent controls, inject-workload button (simulates capability accretion), three live index gauges (Overlap, Concentration, Vitality). No build step.
The pattern now demonstrates what it describes.