moo-agent 1.0.0__tar.gz

moo_agent-1.0.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+## 1.0.0 (2026-04-16)
+
+### Features
+
+* add a foreman agent to coordinate the rest ([e879474](https://gitlab.com/bubblehouse/moo-agent/commit/e879474e5827261c2be39e62a63525eb7fdef5f1))
+* add agentmux restart <name> for single-agent restart by name ([7bebb9d](https://gitlab.com/bubblehouse/moo-agent/commit/7bebb9d2ce604dfab2bfb27f28962fbe56d3cd6c))
+* add compass to look output, agent fixes, tests ([c68d191](https://gitlab.com/bubblehouse/moo-agent/commit/c68d191181b2aca9d81274edb18e13ff4c34a642))
+* added agent support for local inference....one day ([a901549](https://gitlab.com/bubblehouse/moo-agent/commit/a901549c99bbfd405947abb11fd8b5e06d207420))
+* added cliff and newman agents for mail system testing ([53c8d51](https://gitlab.com/bubblehouse/moo-agent/commit/53c8d51627b4cc1defa33a95b5d10df04f4d5b06))
+* added tool use support to moo-agent ([e8c4efa](https://gitlab.com/bubblehouse/moo-agent/commit/e8c4efab17190898fc2a81b9f3644886c000a46a))
+* **agent:** add MOO_TOKEN_CHAIN env override, dynamic agentmux layout, token chain auto-relay ([bd1246e](https://gitlab.com/bubblehouse/moo-agent/commit/bd1246e317187e9b85b2258b83617bc742b6fba4))
+* **agent:** add temperature config and wire it through to LLM calls ([ada44e6](https://gitlab.com/bubblehouse/moo-agent/commit/ada44e6b4acfa3c903406fd6d983ba0dd45834d8))
+* **agent:** add timer_only and clear_window_on_wakeup config options ([b493586](https://gitlab.com/bubblehouse/moo-agent/commit/b493586ecb7d0c5bc7195c851afc7489b6e6a1e8))
+* **agent:** add token chain auto-relay, dynamic agentmux layout, MOO_TOKEN_CHAIN env override ([2a357bf](https://gitlab.com/bubblehouse/moo-agent/commit/2a357bfd45f4d0017806241f08cb4a320480bdcb))
+* **agent:** cache orchestrator flag at startup and skip post-drain LLM cycles for orchestrators ([ed74dea](https://gitlab.com/bubblehouse/moo-agent/commit/ed74deac7cab456306349c008dfc314c6cb66807))
+* **agent:** instrument LLM cycles and add adaptive stall check via agentmux cycle-age ([c2c4f31](https://gitlab.com/bubblehouse/moo-agent/commit/c2c4f3183dc6e0c351d956702ba0b59980101cbf))
+* **agent:** parse [Mail] inbox lines on token receipt, add send_report tool ([0220461](https://gitlab.com/bubblehouse/moo-agent/commit/0220461892197ade514e1ecd01aed1549bcc67c3))
+* **agent:** plumb 'of' parameter through divine tool wrapper ([044b571](https://gitlab.com/bubblehouse/moo-agent/commit/044b5710a0203df57335ecb3d542b1c74914ab27))
+* **agent:** rename coordination tools to post_board/read_board/write_book/read_book/clear_topic, drop room-list injection ([bc5d19c](https://gitlab.com/bubblehouse/moo-agent/commit/bc5d19c84345548891dd46889f90b3321c6b06ae))
+* **agents:** add inspectors, neighbours, wanderer agent groups ([3815ed3](https://gitlab.com/bubblehouse/moo-agent/commit/3815ed36a9f571b0bbcb927fe0d0c40750e0eaec))
+* configure tradesmen agents into iterative loop ([c6424dc](https://gitlab.com/bubblehouse/moo-agent/commit/c6424dcb7bcc6ea28ce6ac7c93b87c58da1ed4f9))
+* expose new navigation verbs as agent tool specs ([7796f61](https://gitlab.com/bubblehouse/moo-agent/commit/7796f614aeaa5a0fc71e7ff9b3f3f409c17a3a01))
+* implemented moo-agent for autonomous experiments ([ed0c55f](https://gitlab.com/bubblehouse/moo-agent/commit/ed0c55fdd1fd60861085d9428a24fc507c398f9e))
+* split builder agent into mutiple simpler agents ([885a339](https://gitlab.com/bubblehouse/moo-agent/commit/885a3398a957391a451f25a9c634a377f8175863))
+* support Bedrock in moo-agent ([865b4df](https://gitlab.com/bubblehouse/moo-agent/commit/865b4df4eb04423cf542251a00a03492ef1ffa76))
+
+### Bug Fixes
+
+* add teleport-to syntax, look-at global lookup, huh2 cardinal aliases, coerce tool args to str ([df76cb5](https://gitlab.com/bubblehouse/moo-agent/commit/df76cb5d24438ada2ac1bca7aafd01d9690b775c))
+* added stocker agent for consumables, other agent updates ([4096bcb](https://gitlab.com/bubblehouse/moo-agent/commit/4096bcbe3d1403aa5ccb19c04ebaff5dd2fb7edc))
+* after a script, print a summary of what you did ([e185a7d](https://gitlab.com/bubblehouse/moo-agent/commit/e185a7d4c255a89d776c159c54646351821259af))
+* agent should pre-generate a list of commands rather than doing each one by one ([d2d8451](https://gitlab.com/bubblehouse/moo-agent/commit/d2d8451fa306a0641adb2dc50c6a6e8f0db7b6e1))
+* agent stall on non-response ([1543547](https://gitlab.com/bubblehouse/moo-agent/commit/1543547084e0e47170d6ab6aa229434f885d8dde))
+* agent updates to self-train after mistakes ([653be56](https://gitlab.com/bubblehouse/moo-agent/commit/653be56769364af9321fed3410909fe267b94f49))
+* **agent:** add command-loop detector, remove stale check_inbox queuing, and broaden special-token regex ([a68bdba](https://gitlab.com/bubblehouse/moo-agent/commit/a68bdbaa77dd4f6dbbf184b363df19f9cd402eb2))
+* **agent:** detect page verb in both conjugations for they/them players ([bdf785a](https://gitlab.com/bubblehouse/moo-agent/commit/bdf785a3efde27b523666a11832a93707ef1c2d0))
+* **agentmux:** correctly stop a single named agent without killing the whole group ([ab58a58](https://gitlab.com/bubblehouse/moo-agent/commit/ab58a586400bce15a3f7e0f658abe57db3e1be6c))
+* **agent:** normalize bare integer object references in tool arg translation ([57a5103](https://gitlab.com/bubblehouse/moo-agent/commit/57a5103720860e0f7297455a69e10fef0afc69dd))
+* **agent:** set current_goal on [Done] Blocked and relay token as 'Token: X go.' to avoid LLM misreading prior agent's completion message ([0adcfca](https://gitlab.com/bubblehouse/moo-agent/commit/0adcfca70e64957164661b9dcdc21cc0c575c3e5))
+* **agents:** harden warden master key handling and reorder inspectors token chain ([9abaa04](https://gitlab.com/bubblehouse/moo-agent/commit/9abaa0420d55d932cd6b793b213a9f4196b4d3c1))
+* **agents:** reduce Foreman stall timeout to 180s based on observed P95 runtimes and update token chain order ([eaec79d](https://gitlab.com/bubblehouse/moo-agent/commit/eaec79d53a721e0e342cb01a8ee3d7a90b658a1e))
+* **agents:** restore LM Studio settings, fix Harbinger SOUL, improve alias guidance ([582cf9d](https://gitlab.com/bubblehouse/moo-agent/commit/582cf9d92e8a7fdb6b2064e41d463e4cdc26fc60))
+* **agents:** switch to claude-sonnet-4-6, cap harbinger NPC spawn rate to 10% ([b3c534f](https://gitlab.com/bubblehouse/moo-agent/commit/b3c534f19852d82e28f9d2bb5a2f8696bf183fbc))
+* **agent:** strip endoftext token leakage from LM Studio responses ([1094d5c](https://gitlab.com/bubblehouse/moo-agent/commit/1094d5c8f7b6dfc03ab159b12c52e90ff6af8d04))
+* **agent:** strip Harmony special tokens from LLM output and resumed logs ([a4481c1](https://gitlab.com/bubblehouse/moo-agent/commit/a4481c19d091c34c503734515401c5d95cc92f9d))
+* **agent:** suppress prior session summary for all page-triggered agents to prevent stale context injection ([b32a25d](https://gitlab.com/bubblehouse/moo-agent/commit/b32a25d801f99458b44c5e9427911ad546fad448))
+* brain updates for gemma ([5b97e45](https://gitlab.com/bubblehouse/moo-agent/commit/5b97e4510a58d4118be4cc5c39f57ec2c3ee7869))
+* **build:** use packages=moo for correct PEP 420 namespace wheel layout ([9bcc3d9](https://gitlab.com/bubblehouse/moo-agent/commit/9bcc3d924461241b9db83288cdf56b799372d38b))
+* **ci:** add package.json for semantic-release npm tooling ([177d361](https://gitlab.com/bubblehouse/moo-agent/commit/177d36116539e674aec76a821c53504f7e9ef09d))
+* **ci:** add pylint-gitlab to dev dependencies for lint reporters ([3ed1bf5](https://gitlab.com/bubblehouse/moo-agent/commit/3ed1bf55619e765b11e301ac49026c7a9e6a3513))
+* **ci:** consolidate jobs and fix sdist/dev-dep issues ([6118fc6](https://gitlab.com/bubblehouse/moo-agent/commit/6118fc6b61e5eeead80a42762ded4f6beff2d544))
+* created agentmux script for agent-trainer ([88953fa](https://gitlab.com/bubblehouse/moo-agent/commit/88953fa5a51c9f90481006628cb465e3bf457256))
+* dont display output separators ([3d2f35b](https://gitlab.com/bubblehouse/moo-agent/commit/3d2f35b8e560af8e314e4e7c8e8bbc2ed8dc2189))
+* dont silently discard extra markdown blocks ([0d8cf12](https://gitlab.com/bubblehouse/moo-agent/commit/0d8cf12d57f70b02f6a9342839366809a70299be))
+* eagerly flush the buffer so content doesnt get lost by the agent ([88730fc](https://gitlab.com/bubblehouse/moo-agent/commit/88730fcde8a64ab1a7542efa99449ce46b40715f))
+* encourage agent to pre-generate a script of commands it needs to run ([38606be](https://gitlab.com/bubblehouse/moo-agent/commit/38606bebdb26acb4cc04bf3be56033f6b440ef43))
+* futher agent bugs ([76661e8](https://gitlab.com/bubblehouse/moo-agent/commit/76661e8a0c23828d3496a87748864b2ce67a1496))
+* handle ssh reconnection and other agent issues ([15bb3c9](https://gitlab.com/bubblehouse/moo-agent/commit/15bb3c93127025f485770b3d7949835989b6d560))
+* improve agent context and resume behavior ([7de25a7](https://gitlab.com/bubblehouse/moo-agent/commit/7de25a70848cef136266a00b9970d99cf9b6687a))
+* improve agent permission and multiuser performance ([49ba120](https://gitlab.com/bubblehouse/moo-agent/commit/49ba12053a52b8a9e5baffda34bbbd2c3199e9db))
+* improve agent text handling ([e3b80f5](https://gitlab.com/bubblehouse/moo-agent/commit/e3b80f5715c75c74d565c77b22aba022be7278b0))
+* improved agent token handling, test updates ([40a9609](https://gitlab.com/bubblehouse/moo-agent/commit/40a9609b3a8164f871a502dc422e3e7f42ab01ab))
+* more agent edge cases ([34165ec](https://gitlab.com/bubblehouse/moo-agent/commit/34165ec1e93456c76aba552acaf59d965083b477))
+* more agent edge cases ([9c09861](https://gitlab.com/bubblehouse/moo-agent/commit/9c09861afba6ba08b17839afa8ff5936114efdf1))
+* more agent training ([485ab2f](https://gitlab.com/bubblehouse/moo-agent/commit/485ab2f5b321111240f3390c37654ec5df0d8217))
+* more agent tuning ([3b039d1](https://gitlab.com/bubblehouse/moo-agent/commit/3b039d19eb8e04b76fd88ef052870af0f90a04f2))
+* more agent tuning ([2cf257d](https://gitlab.com/bubblehouse/moo-agent/commit/2cf257d2bfca06753ac2a6991ed294891d652a00))
+* more script handling issues ([1812182](https://gitlab.com/bubblehouse/moo-agent/commit/1812182d433c99ea7a98c36086a1044434046270))
+* more scroll handling, other agent fixes ([1e8534b](https://gitlab.com/bubblehouse/moo-agent/commit/1e8534b69034d4702813f1ba6b7c880d9eda79da))
+* mypy typing errors ([6256f90](https://gitlab.com/bubblehouse/moo-agent/commit/6256f9085b9dedaafe0a0c8117d5651110de5811))
+* post-run agent updates ([40d9842](https://gitlab.com/bubblehouse/moo-agent/commit/40d98424b31b2a688b4a5b5ae1e80fa73f719bf6))
+* refactored agent baseline knowledge, created new unused stocker agent ([3d2e7bf](https://gitlab.com/bubblehouse/moo-agent/commit/3d2e7bfbd25fe45fa9defa44d8095c3f37c99d6a))
+* scroll handling in agent TUI ([091d0dc](https://gitlab.com/bubblehouse/moo-agent/commit/091d0dcc56780d0131b9755e5c760aaf963bacd8))
+* shell and [@edit](https://gitlab.com/edit) edge-case handling, agent fixes ([4e25888](https://gitlab.com/bubblehouse/moo-agent/commit/4e258887fd4927156eb7100ce101fef2467aa347))
+* style update ([bfe9908](https://gitlab.com/bubblehouse/moo-agent/commit/bfe9908d87cb3c0f618354e631b650c4c59bfaee))
+* **tests:** update locked container assertion and add missing _FakeSSHConfig to brain tests ([73b1fa8](https://gitlab.com/bubblehouse/moo-agent/commit/73b1fa860d346edb66bf8d3f89de4c9000212f7a))
+* try to translate bare tool-call syntax before sending as MOO command ([c946386](https://gitlab.com/bubblehouse/moo-agent/commit/c94638689bf8dbe069a72478c57dee3da1b9b3cf))
+* use bedrock by default, other startup fixes ([b0c7c35](https://gitlab.com/bubblehouse/moo-agent/commit/b0c7c3569e26ee6ec9b5d47b244166cf562be720))
+* **verbs:** remove drop/take/get aliases from container/thing dispatch to prevent ambiguity ([31e6df3](https://gitlab.com/bubblehouse/moo-agent/commit/31e6df3454272ab5ce8f9ef76d70640979f68f01))

moo_agent-1.0.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: moo-agent
+Version: 1.0.0
+Summary: Autonomous AI agent client for DjangoMOO servers.
+Project-URL: Repository, https://gitlab.com/bubblehouse/moo-agent
+Author-email: Phil Christensen <phil@bubblehouse.org>
+License: AGPL
+Requires-Python: <3.12,>=3.11
+Requires-Dist: anthropic>=0.50.0
+Requires-Dist: asynciolimiter>=1.0.0
+Requires-Dist: asyncssh[bcrypt]<3,>=2.14.0
+Requires-Dist: mistune>=3.0.0
+Requires-Dist: openai>=2.30.0
+Requires-Dist: prompt-toolkit<4,>=3.0.39
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.5.3
+Description-Content-Type: text/markdown
+
+# moo-agent
+
+Autonomous AI agent client for
+[DjangoMOO](https://gitlab.com/bubblehouse/django-moo) servers.
+
+`moo-agent` connects to a running MOO server via SSH and drives an AI persona using an
+LLM backend (Anthropic, AWS Bedrock, or a local LM Studio model). The agent reads its
+personality and operational rules from a `SOUL.md` file and can learn new rules at
+runtime via `SOUL.patch.md`.
+
+## Installation
+
+```bash
+pip install moo-agent
+```
+
+## Quick Start
+
+```bash
+# Initialize a new agent configuration directory
+moo-agent init --name MyAgent \
+    --host moo.example.com --port 8022 \
+    --user myagent ./my-agent
+
+# Run the agent
+moo-agent run ./my-agent
+```
+
+## Documentation
+
+Full documentation is available at [ReadTheDocs](https://moo-agent.readthedocs.io/).
+
+## License
+
+AGPL — see [LICENSE](LICENSE).

moo_agent-1.0.0/README.md

@@ -0,0 +1,35 @@
+# moo-agent
+
+Autonomous AI agent client for
+[DjangoMOO](https://gitlab.com/bubblehouse/django-moo) servers.
+
+`moo-agent` connects to a running MOO server via SSH and drives an AI persona using an
+LLM backend (Anthropic, AWS Bedrock, or a local LM Studio model). The agent reads its
+personality and operational rules from a `SOUL.md` file and can learn new rules at
+runtime via `SOUL.patch.md`.
+
+## Installation
+
+```bash
+pip install moo-agent
+```
+
+## Quick Start
+
+```bash
+# Initialize a new agent configuration directory
+moo-agent init --name MyAgent \
+    --host moo.example.com --port 8022 \
+    --user myagent ./my-agent
+
+# Run the agent
+moo-agent run ./my-agent
+```
+
+## Documentation
+
+Full documentation is available at [ReadTheDocs](https://moo-agent.readthedocs.io/).
+
+## License
+
+AGPL — see [LICENSE](LICENSE).

moo_agent-1.0.0/extras/agents/README.md

@@ -0,0 +1,141 @@
+# Autonomous Agents
+
+This directory contains config directories for autonomous agents that connect to a
+DjangoMOO server as persistent players and act independently. Each agent is operated
+via the `moo-agent` CLI.
+
+## Agents
+
+### The Tradesmen — World Builders
+
+The Tradesmen are six specialized agents that work together on the same MOO instance.
+Foreman orchestrates the token chain; the five workers execute in fixed order.
+
+| Agent | What it does |
+|-------|-------------|
+| [foreman](foreman/README.md) | Holds the master token, dispatches it in order, detects stalls, loops automatically |
+| [mason](mason/README.md) | Digs rooms, writes descriptions, wires exits (`$player`) |
+| [tinker](tinker/README.md) | Creates interactive `$thing` objects and secret exits via verbs (`$programmer`) |
+| [joiner](joiner/README.md) | Creates `$furniture` and `$container` objects (`$player`) |
+| [harbinger](harbinger/README.md) | Creates one NPC per ~10% of rooms (`$programmer`) |
+| [stocker](stocker/README.md) | Stocks containers with consumables and dispensers (`$programmer`) |
+
+**Run order:** Start Foreman first (or alongside all workers). Foreman pages Mason to
+begin and orchestrates the full chain:
+
+```
+Mason → Tinker → Joiner → Harbinger → Stocker → (back to Mason)
+```
+
+To launch all six at once, use the `groups/` config:
+
+```bash
+extras/skills/agent-trainer/scripts/agentmux start groups/tradesmen.conf
+extras/skills/agent-trainer/scripts/agentmux restart mason  # restart one agent
+extras/skills/agent-trainer/scripts/agentmux stop groups/tradesmen.conf
+```
+
+### The Mailmen — Mail System Load Agents
+
+Two character-driven agents that stress-test the mail system (`@mail`, `@send`,
+`@reply`, pagination, `Message`/`MessageRecipient` models) under sustained use.
+They do not build or explore — they sit at their desks and exchange letters indefinitely.
+
+| Agent | What it does |
+|-------|-------------|
+| [cliff](cliff/README.md) | Pompous postal worker; delivers "little-known facts" (subtly wrong) |
+| [newman](newman/README.md) | Theatrical wronged visionary; escalating grievances and failed schemes |
+
+To launch both at once:
+
+```bash
+extras/skills/agent-trainer/scripts/agentmux start groups/mailmen.conf
+```
+
+The Mailmen use `idle_wakeup_seconds > 0` (periodic autonomous action) rather than
+the token-protocol agents which use `idle_wakeup_seconds = 0` (page-triggered only).
+
+### The Inspectors — Verb Coverage Agents
+
+Sequential token-chain agents that exercise verb paths untouched by the Tradesmen:
+containers, exit locks, and notes/letters.
+
+| Agent | What it tests |
+|-------|--------------|
+| [foreman](foreman/README.md) | Coordinates the Inspectors token chain (same Foreman, different `MOO_TOKEN_CHAIN`) |
+| [quartermaster](quartermaster/) | Container open/close/take/put, opacity, `@lock_for_open` |
+| [warden](warden/) | Exit `@lock`/`@unlock`, key-based traversal |
+| [archivist](archivist/) | Note/letter create, read, `@lock_for_read`, erase, burn |
+
+```bash
+MOO_TOKEN_CHAIN=quartermaster,warden,archivist agentmux --group inspectors start
+```
+
+### The Neighbours — Social System Agents
+
+Two simultaneous timer-based agents in The Neighborhood that exercise whisper,
+emote, gag, ungag, listgag, and paranoid mode.
+
+| Agent | Persona | What it tests |
+|-------|---------|--------------|
+| [gossip](gossip/) | Mrs. Helen Lovejoy | `whisper`, `emote`, `say` |
+| [prude](prude/) | Mrs. Agnes Skinner | `@gag`, `@ungag`, `@listgag`, `@paranoid` |
+
+```bash
+agentmux --group neighbours start
+```
+
+## Shared baseline
+
+`baseline.md` is loaded for every agent before its own `SOUL.md`. It provides:
+sandbox rules, `@eval` pre-imports, the parent class quick reference,
+`#N` object reference rules, and the `SCRIPT:`/`COMMAND:`/`DONE:`/`PLAN:` response format.
+
+Agent-specific knowledge lives in each agent's own `SOUL.md`:
+
+- `@tunnel` syntax → Mason
+- Verb dispatch (`--dspec`, `--iobj`) and verb testing → Tinker
+- NPC `tell` verb pattern and `announce_all_but` → Harbinger
+
+Agents that include a `## Tools` section in their `SOUL.md` additionally use the
+typed tool harness (`moo/agent/tools.py`), which translates structured LLM tool calls
+to correct MOO commands automatically. `baseline.md` covers the fallback text format
+for commands the tool harness doesn't cover.
+
+Do not put agent-specific content in `baseline.md`. Edit an agent's `SOUL.md` instead.
+
+## Directory structure
+
+Each agent directory contains:
+
+```
+agent-name/
+  SOUL.md           # Core identity (hand-authored, never modified at runtime)
+  SOUL.patch.md     # Learned behaviors (append-only, agent-writable)
+  settings.toml     # SSH and LLM credentials (not committed)
+  logs/             # Per-session log files (created automatically)
+  README.md         # Human-readable docs (this kind of file)
+```
+
+## Quick start
+
+Install `moo-agent` (included in the django-moo package after `uv sync`), then:
+
+```bash
+# Scaffold a new agent config directory
+moo-agent init --output-dir extras/agents/my-agent --name MyAgent \
+    --host localhost --port 8022 --user wizard
+
+# Edit SOUL.md and settings.toml, then run
+moo-agent run extras/agents/my-agent
+```
+
+See `docs/source/how-to/moo-agent.md` for full CLI reference and architecture details.
+
+## Adding a new agent
+
+1. Run `moo-agent init` to scaffold the directory.
+2. Edit `SOUL.md`: name, mission, persona, rules of engagement, context links, verb mapping.
+3. Edit `settings.toml`: SSH host/port/credentials, LLM provider.
+4. Create `README.md` documenting purpose, prerequisites, and SOUL.md structure.
+5. Add the agent to the table above.

moo_agent-1.0.0/extras/agents/cliff/README.md

@@ -0,0 +1,93 @@
+# Cliff
+
+Cliff Clavin, pompous postal worker and man of considerable (if subtly wrong) knowledge. Exchanges increasingly insufferable letters with Newman. One of *The Mailmen* — a load-testing agent pair that stress-tests the mail system (`@mail`, `@send`, `@reply`, pagination, `Message`/`MessageRecipient` models) under sustained use. Character framing keeps the generated content varied enough to surface formatting and rendering edge cases that uniform test data would miss.
+
+**Player class:** `$player`
+**SSH user:** `cliff` (account created by `default.py` bootstrap)
+
+## Purpose
+
+Cliff does not build or explore the world. He sits at his desk and composes mail. On each wakeup cycle he:
+
+1. Runs `@mail` to check the inbox
+2. Reads every unread message
+3. Composes exactly one response — either a reply or an unsolicited letter to Newman
+4. Stops
+
+Letters escalate: each is more pedantic and insufferable than the last. Every letter includes at least one "little-known fact" that sounds authoritative but is subtly wrong.
+
+## Prerequisites
+
+- A running DjangoMOO server with the `default` bootstrap (`cliff` account is created automatically)
+- LLM credentials (see Configuring settings.toml)
+- `moo-agent` available after `uv sync`
+
+## Running
+
+```bash
+moo-agent run extras/agents/cliff
+```
+
+Or alongside Newman using the group config:
+
+```bash
+extras/skills/agent-trainer/scripts/agentmux start extras/agents/groups/mailmen.conf
+```
+
+## Configuring settings.toml
+
+`settings.toml` is not committed (contains credentials). The bootstrap creates the
+`cliff` user with a hard-coded dev password. Use `moo-agent init` to scaffold:
+
+```bash
+moo-agent init --output-dir /tmp/cliff-init --name Cliff \
+    --host localhost --port 8022 --user cliff
+cp /tmp/cliff-init/settings.toml extras/agents/cliff/settings.toml
+```
+
+Key settings:
+
+```toml
+[ssh]
+user = "cliff"
+password = "..."   # set by default.py bootstrap
+
+[llm]
+provider = "lm_studio"        # or "anthropic", "bedrock"
+model = "your-model-name"
+
+[agent]
+idle_wakeup_seconds = 120.0   # wakes and composes a letter every two minutes
+memory_window_lines = 20
+max_tokens = 1024
+```
+
+Unlike the Tradesmen, Cliff uses `idle_wakeup_seconds > 0` — he acts on a timer,
+not on token pages.
+
+## SOUL.md structure
+
+| Section | Contents |
+|---------|----------|
+| `# Name` | `Cliff` |
+| `# Persona` | Voice, mannerisms, topics of authority; "little-known fact" opener; Ma Clavin, Norm Peterson references |
+| `## Voice and Mannerisms` | Behavioral rules: pedantry, obliviousness, misremembered expertise |
+| `## Rules` | Operational rules: always escalate, one reply per wakeup, never use the editor, `\n` line breaks in quoted strings |
+| `## Rules of Engagement` | (empty — Cliff reacts to wakeup, not to server patterns) |
+| `## Verb Mapping` | (empty) |
+| `# Mission` | Step-by-step wakeup procedure: always run `@mail` first, read unread, send one reply or new letter, stop |
+
+The Mission section is the most important — it enforces the strict one-reply-per-wakeup discipline that prevents runaway mail loops.
+
+## Behavior notes
+
+- Cliff never walks around, `look`s at rooms, or interacts with objects
+- All output goes through `@reply <n> with "..."` or `@send newman with "Subject: ...\n\n..."`
+- The word `with` is mandatory in both commands
+- `\n\n` after the Subject line; `\n` between paragraphs; no triple-newlines
+
+## Further reading
+
+- Full `moo-agent` CLI reference: `docs/source/how-to/moo-agent.md`
+- Newman: `extras/agents/newman/README.md`
+- Mail verb reference: `moo/bootstrap/default_verbs/player/`

moo_agent-1.0.0/extras/agents/foreman/README.md

@@ -0,0 +1,64 @@
+# Foreman
+
+Foreman is the token orchestrator for the Tradesmen agent chain. It holds the master
+token, dispatches it to each worker in fixed order, relays room lists, detects stalls,
+and loops the chain automatically after each full pass.
+
+## Purpose
+
+Without Foreman, agents pass tokens directly peer-to-peer. A stalled or restarted
+agent silently breaks the chain, requiring human intervention. Foreman centralizes
+custody: every agent reports done to Foreman, and Foreman dispatches to the next. This
+gives one place to observe handoffs and recover from stalls.
+
+## Prerequisites
+
+A `Foreman` player account must exist in the MOO with SSH access. It needs `$player`
+class — no wizard or programmer powers are required.
+
+## How to run
+
+```bash
+uv run moo-agent run extras/agents/foreman
+```
+
+Foreman pages Mason automatically on startup. The full chain then runs without further
+operator involvement:
+
+```
+Foreman → Mason → Foreman → Tinker → Foreman → Joiner → Foreman → Harbinger → Foreman → (loop)
+```
+
+## Configuration
+
+`settings.toml` — fill in the SSH password matching the MOO account. The LLM
+provider defaults to LM Studio. `idle_wakeup_seconds = 60` is required for stall
+detection; do not set it to 0.
+
+## SOUL.md structure
+
+| Section | Purpose |
+|---------|---------|
+| `## Chain Order` | Fixed numbered dispatch sequence |
+| `## Startup` | Pages Mason immediately on first wakeup |
+| `## Token Reception` | Parses done pages, extracts room lists, relays to next agent |
+| `## WAIT Mode` | Instructs Foreman to emit nothing while waiting for a done page |
+| `## Stall Detection` | Documents the automatic code-level stall timer |
+
+## Stall recovery
+
+Stall detection is handled by `_stall_check_loop()` in `brain.py` — a deterministic
+wall-clock timer, not an LLM behavior. When Foreman dispatches a token via `page()`,
+the timestamp is recorded. If no done page arrives within `stall_timeout_seconds`
+(default 300 s, set in `settings.toml`), `brain.py` re-pages the stuck agent directly,
+bypassing the LLM entirely. The timer resets after each alert.
+
+If an agent remains unresponsive after repeated automatic re-pages, Foreman's SOUL.md
+instructs it to emit `say <agent> unresponsive. Operator intervention required.` and
+stop alerting. Process restart is a manual step.
+
+## What Foreman never does
+
+- Creates objects, rooms, or verbs
+- Calls `done()` (runs indefinitely)
+- Modifies the world in any way

moo_agent-1.0.0/extras/agents/harbinger/README.md

@@ -0,0 +1,114 @@
+# harbinger
+
+An autonomous NPC-summoner for DjangoMOO. Harbinger connects as a `$programmer`
+account, visits each room Mason has built, and rolls a random number (0–1) to
+decide whether to create an NPC. Only rooms that roll ≤ 0.10 get an NPC — roughly
+10% of rooms — keeping the world from feeling overrun. Each NPC is a `$player`
+child with a `tell` verb override and a `lines` property that drives its dialogue.
+
+Harbinger is one of *The Tradesmen*, four specialized agents intended to run
+concurrently on the same MOO instance. Run Harbinger after Mason has built the
+room structure.
+
+## When to use it
+
+Run Harbinger when you want to:
+
+- Sprinkle NPCs into a world without overpopulating it
+- Give a small number of rooms a present, reactive voice
+- Delegate NPC authoring entirely — Harbinger writes personality from the room description
+
+## Prerequisites
+
+- A running DjangoMOO server reachable via SSH
+- A `$programmer` account Harbinger can log into (username `harbinger`, created by `default.py` bootstrap)
+- Rooms already built by Mason (Harbinger uses `@realm $room` to discover them)
+- LLM credentials (see Configuring settings.toml below)
+- `moo-agent` available after `uv sync`
+
+## Running
+
+```bash
+moo-agent run extras/agents/harbinger
+```
+
+## Configuring settings.toml
+
+```toml
+[ssh]
+user = "harbinger"
+password = "Bt6wF5jRcU3e"   # set by default.py bootstrap
+
+[llm]
+provider = "lm_studio"
+model = "google/gemma-4-26b-a4b"
+base_url = "http://localhost:1234/v1"
+
+[agent]
+command_rate_per_second = 1.0
+memory_window_lines = 20
+max_tokens = 2048
+```
+
+## SOUL.md structure
+
+| Section | Contents |
+|---------|----------|
+| `# Name` | `Harbinger` |
+| `# Mission` | Create NPCs in ~10% of rooms via random roll; one well-crafted NPC beats five generic ones |
+| `# Persona` | Patient, deliberate; finds the right voice for each spirit; avoids generic greetings |
+| `## Room Traversal` | `@realm $room` at start; `PLAN:` tracking; `@show here` before rolling |
+| `## The Random Roll` | `@eval "import random; print(random.random())"` — proceed only if result ≤ 0.10 |
+| `## NPC Creation` | Six-step sequence: `@create`, `@describe`, set `lines` via `@eval`, write `tell` verb, `@move`, `@obvious` |
+| `## NPC Scope` | Only `$player` children — never `$thing`, `$furniture`, or `$container` |
+| `## Dialogue` | 3–6 lines; atmospheric, specific, odd; no "Hello, traveler." |
+| `## Awareness` | "Mason built the rooms. Tinker adds interactive objects. Joiner adds furniture." |
+| `## Rules of Engagement` | Reflexive triggers: errors, random result > 0.10 → skip |
+| `## Context` | Links: `object-model.md`, `verb-patterns.md` (for `tell` pattern) |
+| `## Tools` | `go, create_object, write_verb, alias, show, look, done` |
+| `## Verb Mapping` | Navigation intents; inspect/audit shortcuts |
+
+## NPC tell verb pattern
+
+Harbinger's SOUL.md carries the NPC `tell` verb pattern that was removed from
+`baseline.md` during the Tradesmen refactor:
+
+```python
+import random
+from moo.sdk import context
+lines = this.get_property('lines')
+if lines and args and ': ' in args[0]:
+    line = random.choice(lines)
+    this.location.announce_all_but(this, f'{this.name} says: {line}')
+```
+
+The critical rule: **never call `this.location.announce_all(...)` inside `tell`** —
+`announce_all` calls `tell` on every object in the room including the NPC, causing
+infinite recursion. Always use `announce_all_but(this, message)`.
+
+## $programmer requirement
+
+Harbinger needs a `$programmer` account because it uses `@edit verb` (to write the
+NPC `tell` override) and `@eval` (for the random roll and setting the `lines`
+property). The `default.py` bootstrap creates the `harbinger` account as `$programmer`.
+
+## Soul evolution
+
+Harbinger accumulates learned rules in `SOUL.patch.md` at runtime. The most common
+stale entries are observations about specific NPCs that no longer exist after a DB
+reset. Audit before restarting.
+
+## What's in this folder
+
+| Path | Purpose |
+|------|---------|
+| `SOUL.md` | Core identity — hand-authored, never modified at runtime |
+| `SOUL.patch.md` | Learned behaviors — append-only, agent-writable; delete to reset |
+| `settings.toml` | SSH and LLM credentials (not committed) |
+| `logs/` | Per-session log files (not pruned automatically) |
+
+## Further reading
+
+- Full `moo-agent` CLI reference: `docs/source/how-to/moo-agent.md`
+- Object model and NPC pattern: `extras/skills/game-designer/references/object-model.md`
+- Verb patterns for `tell` override: `extras/skills/game-designer/references/verb-patterns.md`