From cd487a61bc1783b21a70cd9c7a52990ce57bfab1 Mon Sep 17 00:00:00 2001
From: Levi Neely <lkn@darkstar.example.net>
Date: Thu, 19 Mar 2026 00:33:06 +0100
Subject: [PATCH] Add docs/toys.md: inbox_refresh.py and msgtrace.py

---
 docs/toys.md          | 24 ++++++++++++++++++++++
 scripts/9p-read-inbox | 46 -------------------------------------------
 scripts/Alog          | 12 -----------
 3 files changed, 24 insertions(+), 58 deletions(-)
 create mode 100644 docs/toys.md
 delete mode 100755 scripts/9p-read-inbox
 delete mode 100755 scripts/Alog

diff --git a/docs/toys.md b/docs/toys.md
new file mode 100644
index 0000000..5a1d30b
--- /dev/null
+++ b/docs/toys.md
@@ -0,0 +1,24 @@
+# Toys
+
+Small utilities in `scripts/` that build on the 9P API.
+
+## inbox_refresh.py
+
+Auto-refreshes the `/AnviLLM/inbox` window in Acme whenever a new message arrives. Listens to `anvillm/events` for `UserRecv` events and rewrites the inbox window body via the Acme 9P filesystem.
+
+```sh
+python3 scripts/inbox_refresh.py
+```
+
+Requires an open `/AnviLLM/inbox` window in Acme.
+
+## msgtrace.py
+
+Real-time message sequence diagram generator. Listens to `anvillm/events` for `UserSend`/`BotSend` events and renders a PlantUML sequence diagram in a local web UI. Useful for visualizing inter-agent communication.
+
+```sh
+python3 scripts/msgtrace.py
+# Open http://localhost:8089
+```
+
+The web UI auto-refreshes every 2 seconds, supports pan/zoom, and has a reset button to clear the trace. Requires `plantuml` in PATH.
diff --git a/scripts/9p-read-inbox b/scripts/9p-read-inbox
deleted file mode 100755
index 9896f3c..0000000
--- a/scripts/9p-read-inbox
+++ /dev/null
@@ -1,46 +0,0 @@
-#!/bin/bash
-# Read next message from bot's inbox and mark it complete
-# Usage: 9p-read-inbox [--help]
-
-set -e
-
-if [ "$1" = "--help" ]; then
-    echo "Usage: 9p-read-inbox"
-    echo "Read the next message from the bot's inbox and mark it complete"
-    exit 0
-fi
-
-if [ -z "$AGENT_ID" ]; then
-    echo "Error: AGENT_ID environment variable not set" >&2
-    exit 1
-fi
-
-INBOX_PATH="agent/$AGENT_ID/inbox"
-
-# List messages
-MESSAGES=$(9p ls "$INBOX_PATH" 2>/dev/null) || {
-    echo "Error: Failed to list inbox" >&2
-    exit 1
-}
-
-if [ -z "$MESSAGES" ]; then
-    echo "No messages"
-    exit 0
-fi
-
-# Read first message
-FIRST_MSG=$(echo "$MESSAGES" | head -1)
-MSG_JSON=$(9p read "$INBOX_PATH/$FIRST_MSG") || {
-    echo "Error: Failed to read message" >&2
-    exit 1
-}
-
-# Display the message body
-echo "$MSG_JSON" | jq -r '"[Message from \(.from)]", "Type: \(.type)", "Subject: \(.subject)", "", .body'
-
-# Mark as complete by writing to ctl file (strip .json extension)
-MSG_ID="${FIRST_MSG%.json}"
-echo "complete $MSG_ID" | 9p write "agent/$AGENT_ID/ctl" || {
-    echo "Warning: Failed to mark message as complete" >&2
-    exit 1
-}
diff --git a/scripts/Alog b/scripts/Alog
deleted file mode 100755
index d458ddd..0000000
--- a/scripts/Alog
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env rc
-
-# Alog - Stream AnviLLM audit log to Acme window
-
-# Create window and get its ID
-winid=`{9p read acme/new/ctl | awk '{print $1}'}
-echo name /AnviLLM/Audit | 9p write acme/$winid/ctl
-echo clean | 9p write acme/$winid/ctl
-
-# Stream audit log to window
-9p read anvillm/audit | 9p write acme/$winid/data
-