Skip to content

Releases

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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 15 Apr 07:57

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

v1.8.2 — Live browser viewer for the Teaching Colony

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 15 Apr 06:21

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

v1.8.1 — DSL dual-key bypass closed

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 16:28

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:

  1. _change_action_class inferred mirror_patch (not mirror_capability_add)
  2. ACTION_BLAST_RADIUS[mirror_patch] is not in the table → default Local
  3. Blast-radius-ceiling check passed trivially
  4. Forbidden-list keyword match missed ("add new teaching" doesn't appear in "Patch mirror with keys: ['capability_add']")
  5. _apply_changes deep-merged capability_add as 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:

  1. test_legacy_capability_add_key_is_rejected — provokes the exact v1.6.x bypass
  2. test_random_unknown_dsl_key_is_rejected — generalises to any non-DSL key
  3. test_patch_key_still_works_for_legitimate_literal_updates — confirms the explicit patch escape hatch survives
  4. test_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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 15:50

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_agent in the Claude Code substrate:
    • Prompt caching — cache_control: ephemeral on 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.
  • Session budget — examples/teaching_colony/colony/logic/budget.py. Budget class tracking all four Anthropic usage counters. TEACHING_COLONY_TOKEN_BUDGET env 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_KEY and run with pytest -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.chat

Known gaps after v1.8.0

  • No research walks yet. research, status, cancel, knows, capabilities are all v1.9+.
  • No tool use. fetch_url, extract_links, score_links are 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 this kind 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_agent and update_mirror still 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)

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 14:49

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

  1. 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.
  2. 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[].
  3. The Comprehension Contract was not enforced — update_mirror did none of the checks substrate-contract.md promised.
  4. The event stream was duplicated — driver and adapter emitted the same logical actions with different names.
  5. Mirror writes polluted git-tracked files — every run left colony/mirrors/teacher-agent.yaml modified.
  6. The classifier accepted caller-supplied blast_radius overrides — 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, patch as 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_mirror performs 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 specific ContractViolation subclass.
  • 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_event is 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:

  1. Teacher's beekeeping answer contains "worker" (proves the canned branch fired)
  2. Teacher's Agent Colony answer contains "Mirror" (proves the new capability is used)
  3. Teacher's Mirror contains both capabilities under capabilities.capabilities[]
  4. No floating capability_add key at the root of the Mirror
  5. Classification event with review_regime: Peer Review
  6. cosign.granted event with granted: True
  7. mirror.updated event 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_agent and update_mirror still raise NotImplementedError. Target: v1.8+ when research-preview access is available.
  • v1.7.0 ships with write_kb and co_sign as 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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 10:17

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:

  1. 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.
  2. Run 2 — reset and re-run to verify determinism. Confirm the same mock-mode colony produces the same observable events on repeated runs.
  3. 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)

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 09:44

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) -> Classification

Two 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 behind NotImplementedError pending v1.7+ completion. Ships with api-research.md (first honest adequacy report of a real substrate against the Agent Colony contract) and gaps.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 --mock

Both 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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 08:15

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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 13 Apr 20:29

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) citations
  • CHANGELOG.md: v1.4.0 entry
  • CITATION.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

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 13 Apr 18:53

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 ceiling
  • nfrs: — inherited colony NFRs from Constitutional Memory + agent-specific SLO commitments
  • valuation: — four-perspective scoring (self / peer / audit / human)
  • critical_path: inside relationships: — 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.py

A 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.html

Self-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.