tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename metadata directory .hermes to .mam in backplane scripts and documents

Browse Source
This commit is contained in:
Godopu
2026-06-22 14:06:13 +09:00
parent 30e447189e
commit 9735258bc5
22 changed files with 81 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/lib.sh
+4 -4
View File
@@ -16,7 +16,7 @@
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"
AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.hermes/agent-sessions.yaml}"
AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.mam/agent-sessions.yaml}"
# Workspace-relative defaults with environment overrides (Phase Z)
HOME_DIR="${HOME_DIR:-$WORKSPACE_ROOT}"
@@ -439,7 +439,7 @@ def db_exists(uuid):
def hermes_exists(uuid):
hdb = f"{home}/.hermes/state.db"
hdb = f"{home}/.mam/state.db"
if not os.path.exists(hdb):
return False
try:
@@ -529,7 +529,7 @@ elif agent == 'agy':
if cand and db_exists(cand):
emit(cand)
elif agent == 'hermes':
hdb = f"{home}/.hermes/state.db"
hdb = f"{home}/.mam/state.db"
if os.path.exists(hdb):
cand = None
try:
@@ -724,7 +724,7 @@ start_watchdog() {
local job_id="$1"
local workdir="${2:-$PWD}"
local watchdog_script="$workdir/.agents/skills/tmux-agent-orchestrate-monitor/scripts/watchdog.sh"
local log_file="$workdir/.hermes/jobs/${job_id}.watchdog.log"
local log_file="$workdir/.mam/jobs/${job_id}.watchdog.log"
if [ ! -x "$watchdog_script" ]; then
echo "ERROR: watchdog not found or not executable: $watchdog_script" >&2
.agents/skills/tmux-agent-orchestrate-create/SKILL.md
+4 -4
View File
@@ -1,6 +1,6 @@
---
name: tmux-agent-orchestrate-create
description: "Create a new agent session (claude, antigravity/agy) in a dedicated tmux session for context-preserving long-running work. Always creates a tmux session — never backgrounds with nohup/disown. Writes the new session to .hermes/agent-sessions.yaml. Use when you want to start a fresh agent (no prior UUID) for a new project workspace."
description: "Create a new agent session (claude, antigravity/agy) in a dedicated tmux session for context-preserving long-running work. Always creates a tmux session — never backgrounds with nohup/disown. Writes the new session to .mam/agent-sessions.yaml. Use when you want to start a fresh agent (no prior UUID) for a new project workspace."
version: 1.0.0
author: godopu
license: MIT
@@ -16,7 +16,7 @@ metadata:
# Multi-Agent Create — Start a Fresh Agent in a tmux Session
> **Companion skills**: `tmux-agent-orchestrate-resume` (resume an existing UUID), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Single source of truth**: `./.hermes/agent-sessions.yaml` (this skill writes to it; never read it ad-hoc — go through this skill).
> **Single source of truth**: `./.mam/agent-sessions.yaml` (this skill writes to it; never read it ad-hoc — go through this skill).
## What this skill does
@@ -137,7 +137,7 @@ TMUX_EPOCH=$(tmux list-sessions -F '#{session_created}' -t "$SESSION_NAME" 2>/de
## Registering the session in agent-sessions.yaml
After spawn, append a new `tmux_sessions[]` entry to `.hermes/agent-sessions.yaml`:
After spawn, append a new `tmux_sessions[]` entry to `.mam/agent-sessions.yaml`:
```yaml
- name: <SESSION_NAME>
@@ -200,7 +200,7 @@ tmux list-panes -t "$SESSION_NAME" -F 'cmd=#{pane_current_command} cwd=#{pane_cu
# 3. agent-sessions.yaml has the new entry
python3 -c "
import yaml
d = yaml.safe_load(open('.hermes/agent-sessions.yaml'))
d = yaml.safe_load(open('.mam/agent-sessions.yaml'))
names = [s['name'] for s in d['tmux_sessions']]
assert '$SESSION_NAME' in names, 'session not registered'
print('OK:', names)
.agents/skills/tmux-agent-orchestrate-delegate-job/README.md
+1 -1
View File
@@ -7,5 +7,5 @@
- 브로커 PoC→운영 전환: [`mqtt-broker-setup.md`](./mqtt-broker-setup.md)
- 레지스트리 포맷/동시성: [`registry.md`](./registry.md)
- 참조 구현: [`tmux-agent-orchestrate-delegate-job`](./tmux-agent-orchestrate-delegate-job) (bash wrapper), [`scripts/publish_event.py`](./scripts/publish_event.py), [`scripts/job_subscriber.py`](./scripts/job_subscriber.py), [`scripts/registry.py`](./scripts/registry.py), [`scripts/mqtt_common.py`](./scripts/mqtt_common.py)
- 영구 감사 로그: `.hermes/delegate_job_logs/<job_id>/` (`meta.json`·`events.ndjson`·`status.json`)
- 영구 감사 로그: `.mam/delegate_job_logs/<job_id>/` (`meta.json`·`events.ndjson`·`status.json`)
— `tmux-agent-orchestrate-delegate-job logs <id>` 또는 `tmux-agent-orchestrate-delegate-job logs --list`로 조회 (SKILL.md "Audit Logs" 참조)
.agents/skills/tmux-agent-orchestrate-delegate-job/SKILL.md
+9 -9
View File
@@ -27,7 +27,7 @@ canonical concrete instance.
The model is deliberately small. A **job** is one delegated task. An **agent**
is a worker (a claude-code tmux session, a codex run, a human). The **registry**
(`.hermes/jobs/<id>.json`) holds everything about a job so nothing important
(`.mam/jobs/<id>.json`) holds everything about a job so nothing important
lives in environment variables — which means one tmux session can process many
jobs sequentially, and many sessions can fan out in parallel, with no env
collisions. The **event channel** is one MQTT topic per job carrying JSON
@@ -83,7 +83,7 @@ tmux-agent-orchestrate-delegate-job submit \
# subscriber pid: …
# agent launched in tmux session: demo
# subscriber output: <one line per event>
# /path/to/project/.hermes/delegate_job_logs/<JID> ← audit log dir
# /path/to/project/.mam/delegate_job_logs/<JID> ← audit log dir
# 2) at any time, query the job or its audit log
tmux-agent-orchestrate-delegate-job status --job <JID>
@@ -148,9 +148,9 @@ One topic per job: `python/mqtt/jobs/<job_id>/events`. Payload (JSON, UTF-8,
## Registry Format
```
.hermes/jobs/<id>.json # metadata record (single source of truth)
.hermes/jobs/<id>.events.log # append-only JSON-lines log (debug, optional)
.hermes/jobs/.lock # fcntl advisory lock for the registry
.mam/jobs/<id>.json # metadata record (single source of truth)
.mam/jobs/<id>.events.log # append-only JSON-lines log (debug, optional)
.mam/jobs/.lock # fcntl advisory lock for the registry
```
The record holds `status`, `prompt`, `agent`, `agent_session`, a `broker` block,
@@ -163,13 +163,13 @@ the atomic rename trick, and multi-session job claiming are in
## Audit Logs
Every job's lifecycle is mirrored to a **persistent, append-only audit log**
under `.hermes/delegate_job_logs/` (override with `DELEGATE_JOB_LOGS_DIR`;
default `<cwd>/.hermes/delegate_job_logs`). Unlike the registry — live state
under `.mam/delegate_job_logs/` (override with `DELEGATE_JOB_LOGS_DIR`;
default `<cwd>/.mam/delegate_job_logs`). Unlike the registry — live state
mutated in place and liable to be cleaned up — the audit log is durable
history you can replay after the fact. It is git-ignored.
```
.hermes/delegate_job_logs/<job_id>/
.mam/delegate_job_logs/<job_id>/
meta.json # registration snapshot: prompt, agent, broker, timeouts, …
events.ndjson # append-only, one JSON event per line, in time order
status.json # current status only (fast point-query)
@@ -371,7 +371,7 @@ has been verified (2026-06-21, 6-batch refactoring sprint):
- [ ] `publisher.py`/`subscriber.py`/`README.md` demo on `python/mqtt/sample`
still works unchanged (regression).
- [ ] **audit log integrity** — for a completed job,
`.hermes/delegate_job_logs/<JID>/events.ndjson` contains `registered` →
`.mam/delegate_job_logs/<JID>/events.ndjson` contains `registered` →
`received started` → `published completed` (in that order), and
`status.json.status == "completed"` matches the registry record. A
logging failure (e.g. read-only log dir) does not break the publish or
.agents/skills/tmux-agent-orchestrate-delegate-job/registry.md
+5 -5
View File
@@ -15,13 +15,13 @@ Reference implementation: [`./scripts/registry.py`](./scripts/registry.py)
## 1. Directory layout
```
.hermes/jobs/
.mam/jobs/
<job_id>.json # job metadata record (schema below)
<job_id>.events.log # append-only JSON-lines event log (debug, optional)
.lock # shared advisory lock (fcntl) for the whole registry
```
`registry_dir` defaults to `.hermes/jobs` and is overridable everywhere via
`registry_dir` defaults to `.mam/jobs` and is overridable everywhere via
`--registry-dir`.
---
@@ -143,13 +143,13 @@ that session.
## 7. Persistent audit log
Separate from the registry, every job is also mirrored to a durable append-only
audit log at `.hermes/delegate_job_logs/<job_id>/` (override with
`DELEGATE_JOB_LOGS_DIR`, default `<cwd>/.hermes/delegate_job_logs`). The registry
audit log at `.mam/delegate_job_logs/<job_id>/` (override with
`DELEGATE_JOB_LOGS_DIR`, default `<cwd>/.mam/delegate_job_logs`). The registry
is **live state** mutated in place; the audit log is **history** that survives
even after the registry dir is cleaned up. It is git-ignored.
```
.hermes/delegate_job_logs/<job_id>/
.mam/delegate_job_logs/<job_id>/
meta.json # registration snapshot (the full job record at register time)
events.ndjson # append-only, one JSON event per line, time-ordered
status.json # current status only (fast point-query)
.agents/skills/tmux-agent-orchestrate-delegate-job/scripts/mqtt_common.py
+6 -6
View File
@@ -71,11 +71,11 @@ _load_dotenv()
# Constants
# --------------------------------------------------------------------------
SCHEMA_VERSION = 1
DEFAULT_REGISTRY_DIR = ".hermes/jobs"
DEFAULT_REGISTRY_DIR = ".mam/jobs"
DEFAULT_TOPIC_ROOT = "python/mqtt/jobs"
LOCK_FILENAME = ".lock"
# Persistent audit-log layout: .hermes/delegate_job_logs/<job_id>/{meta,events,status}.
# Persistent audit-log layout: .mam/delegate_job_logs/<job_id>/{meta,events,status}.
# This is a *separate* artifact from the registry: the registry is the live job
# record (mutated in place), the audit log is an append-only history that
# survives even if the registry dir is cleaned up.
@@ -86,15 +86,15 @@ STATUS_FILENAME = "status.json"
def _default_logs_dir() -> str:
"""Audit-log root. Overridable with ``DELEGATE_JOB_LOGS_DIR``; otherwise
``<cwd>/.hermes/delegate_job_logs`` — we keep audit logs next to the
live registry (``.hermes/jobs/``) so the two runtime artifacts sit
``<cwd>/.mam/delegate_job_logs`` — we keep audit logs next to the
live registry (``.mam/jobs/``) so the two runtime artifacts sit
under the same parent dir and follow the same ``.gitignore`` rule.
The cwd of whichever process emits events (the bash wrapper and
scripts) is used as the anchor."""
env = os.environ.get("DELEGATE_JOB_LOGS_DIR")
if env and env.strip():
return env
return os.path.join(os.getcwd(), ".hermes", "delegate_job_logs")
return os.path.join(os.getcwd(), ".mam", "delegate_job_logs")
LOGS_DIR = _default_logs_dir()
@@ -376,7 +376,7 @@ def _utcnow_precise() -> str:
# --------------------------------------------------------------------------
# Persistent audit log (.hermes/delegate_job_logs/<job_id>/...)
# Persistent audit log (.mam/delegate_job_logs/<job_id>/...)
#
# Every function here is idempotent, concurrency-safe, and *best-effort*: a
# logging failure is swallowed with a logger.warning and never propagated, so it
.agents/skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py
+1 -1
View File
@@ -222,7 +222,7 @@ def _build_parser() -> argparse.ArgumentParser:
help="summarise every job under the logs dir instead")
p_logs.add_argument("--logs-dir", default=None,
help="override the audit-log root (default: $DELEGATE_JOB_LOGS_DIR "
"or <cwd>/.hermes/delegate_job_logs)")
"or <cwd>/.mam/delegate_job_logs)")
p_logs.add_argument("--tail", type=int, default=0,
help="show only the last N events (0 = all)")
p_logs.add_argument("--json", action="store_true",
.agents/skills/tmux-agent-orchestrate-delegate-job/tmux-agent-orchestrate-delegate-job
+1 -1
View File
@@ -37,7 +37,7 @@ pick_python() {
echo "$py_bin"
}
REGISTRY_DIR_DEFAULT=".hermes/jobs"
REGISTRY_DIR_DEFAULT=".mam/jobs"
usage() {
cat <<'EOF'
.agents/skills/tmux-agent-orchestrate-monitor/SKILL.md
+3 -3
View File
@@ -1,6 +1,6 @@
---
name: tmux-agent-orchestrate-monitor
description: "Run a long-lived Kanban worker that polls .hermes/agent-sessions.yaml against the actual tmux/agent runtime state and reconciles them. Use when you want live visibility into which agent sessions are running, which are dead, which have stale YAML entries, and which have new session ids that haven't been recorded yet. Designed to be dispatched as a Kanban goal_mode task (--goal) so it keeps running until the user stops it."
description: "Run a long-lived Kanban worker that polls .mam/agent-sessions.yaml against the actual tmux/agent runtime state and reconciles them. Use when you want live visibility into which agent sessions are running, which are dead, which have stale YAML entries, and which have new session ids that haven't been recorded yet. Designed to be dispatched as a Kanban goal_mode task (--goal) so it keeps running until the user stops it."
version: 1.0.0
author: godopu
license: MIT
@@ -16,7 +16,7 @@ metadata:
# Agent Sessions Monitor — Live Reconciliation via Kanban Worker
> **Companion skills**: `tmux-agent-orchestrate-create` / `tmux-agent-orchestrate-resume` / `tmux-agent-orchestrate-stop` (mutators); this skill is the **observer**.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
> **Single source of truth**: `./.mam/agent-sessions.yaml`.
## What this skill does
@@ -68,7 +68,7 @@ hermes kanban create \
--body "$(cat <<'EOF'
You are the agent-sessions monitor. Every 30 seconds, do:
1. Read .hermes/agent-sessions.yaml
1. Read .mam/agent-sessions.yaml
2. Run `tmux ls` and `tmux list-panes -F 'session=#{session_name} pid=#{pane_pid} cmd=#{pane_current_command} cwd=#{pane_current_path}'`
3. For each session in the YAML, check the corresponding tmux state
4. For each tmux session matching `*-creator-claude` or `*-creator-agy` that's not in the YAML, register it
.agents/skills/tmux-agent-orchestrate-monitor/scripts/watchdog.sh
+2 -2
View File
@@ -12,7 +12,7 @@ fi
JOB_ID="$1"
WORKDIR="$2"
LOG_DIR="$WORKDIR/.hermes/jobs"
LOG_DIR="$WORKDIR/.mam/jobs"
mkdir -p "$LOG_DIR"
@@ -49,7 +49,7 @@ except Exception:
(
cd "$WORKDIR" && timeout 120 .venv/bin/python .agents/skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py \
--job "$JOB_ID" --timeout 120 --idle-timeout 999999 --registry-dir .hermes/jobs > "$LOG_FILE" 2>&1
--job "$JOB_ID" --timeout 120 --idle-timeout 999999 --registry-dir .mam/jobs > "$LOG_FILE" 2>&1
echo "[$(date -u +'%Y-%m-%dT%H:%M:%SZ')] subscriber exited" >> "$LOG_FILE"
) &
.agents/skills/tmux-agent-orchestrate-resume/SKILL.md
+3 -3
View File
@@ -1,6 +1,6 @@
---
name: tmux-agent-orchestrate-resume
description: "Resume an existing agent (claude, antigravity/agy) conversation by UUID into a tmux session. Reads .hermes/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a tmux session of the matching name, and runs `claude -r <id>` or `agy --conversation <id>` inside. Use when you want to reattach to a previous session's context, or revive a session whose tmux died but the agent's conversation is still on disk."
description: "Resume an existing agent (claude, antigravity/agy) conversation by UUID into a tmux session. Reads .mam/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a tmux session of the matching name, and runs `claude -r <id>` or `agy --conversation <id>` inside. Use when you want to reattach to a previous session's context, or revive a session whose tmux died but the agent's conversation is still on disk."
version: 1.0.0
author: godopu
license: MIT
@@ -17,7 +17,7 @@ metadata:
> **Companion skills**: `tmux-agent-orchestrate-create` (start a fresh agent), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Tmux Isolation**: `TMUX_SERVER_NAME` env var를 create에서 설정한 경우, 동일 서버에서 동작합니다. 자세한 격리 패턴은 [tmux-agent-orchestrate-create/SKILL.md](../tmux-agent-orchestrate-create/SKILL.md) 참조.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
> **Single source of truth**: `./.mam/agent-sessions.yaml`.
## What this skill does
@@ -132,7 +132,7 @@ tmux list-panes -t "$SESSION_NAME" -F 'cmd=#{pane_current_command} cwd=#{pane_cu
# 2. agent-sessions.yaml updated
python3 -c "
import yaml
d = yaml.safe_load(open('.hermes/agent-sessions.yaml'))
d = yaml.safe_load(open('.mam/agent-sessions.yaml'))
s = [s for s in d['tmux_sessions'] if s['name'] == '$SESSION_NAME'][0]
print(f' status: {s[\"status\"]}')
print(f' pane.cmd_full: {s[\"pane\"][\"cmd_full\"]}')
.agents/skills/tmux-agent-orchestrate-status/SKILL.md
+2 -2
View File
@@ -17,7 +17,7 @@ metadata:
> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live polling).
> **Tmux Isolation**: `status` 명령은 YAML에 등록된 모든 세션의 격리 서버(`tmux_server` 필드)를 자동으로 조회하여 상태를 확인하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
> **Single source of truth**: `./.mam/agent-sessions.yaml`.
## What this skill does
@@ -30,7 +30,7 @@ This is the "what's running right now?" answer — faster than dispatching `tmux
```bash
command -v tmux
command -v python3
test -f .hermes/agent-sessions.yaml
test -f .mam/agent-sessions.yaml
```
If `agent-sessions.yaml` doesn't exist or is malformed → print clear error, exit 1. **Do not create it.** (Use `tmux-agent-orchestrate-create` first.)
.agents/skills/tmux-agent-orchestrate-status/scripts/status.sh
+4 -4
View File
@@ -24,7 +24,7 @@ if [ "$JSON" = "1" ]; then
exit 0
fi
# Project root (parent of .agents/) holds the tmux-agent-orchestrate-delegate-job .hermes registry.
# Project root (parent of .agents/) holds the tmux-agent-orchestrate-delegate-job .mam registry.
# Resolved relative to this script — no hardcoded absolute path (review item 6).
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../" && pwd)"
@@ -95,9 +95,9 @@ def get_job_status(s):
# Candidate locations (review item 6: project-root-relative, no hardcoded abs paths):
# 1) cwd-relative registry 2) project-root registry 3) project-root audit log
candidates = [
os.path.join('.hermes', 'jobs', f"{jid}.json"),
os.path.join(project_root, '.hermes', 'jobs', f"{jid}.json"),
os.path.join(project_root, '.hermes', 'delegate_job_logs', jid, 'status.json'),
os.path.join('.mam', 'jobs', f"{jid}.json"),
os.path.join(project_root, '.mam', 'jobs', f"{jid}.json"),
os.path.join(project_root, '.mam', 'delegate_job_logs', jid, 'status.json'),
]
for path in candidates:
if os.path.exists(path):
.agents/skills/tmux-agent-orchestrate-stop/SKILL.md
+3 -3
View File
@@ -1,6 +1,6 @@
---
name: tmux-agent-orchestrate-stop
description: "Stop an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml. Default stops gracefully and marks status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
description: "Stop an agent tmux session (claude, antigravity/agy) and update .mam/agent-sessions.yaml. Default stops gracefully and marks status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
version: 1.0.0
author: godopu
license: MIT
@@ -17,7 +17,7 @@ metadata:
> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-monitor` (live status).
> **Tmux Isolation**: `stop` 명령은 YAML의 `tmux_server` 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정할 필요가 없습니다.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
> **Single source of truth**: `./.mam/agent-sessions.yaml`.
## What this skill does
@@ -37,7 +37,7 @@ The stop command is always **graceful by default**:
```bash
SESSION_NAME=<workspace>-creator-<agent> # convention
AGENT_SESSIONS_YAML=.hermes/agent-sessions.yaml
AGENT_SESSIONS_YAML=.mam/agent-sessions.yaml
# 1) Session is registered?
python3 -c "
.agents/skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh
+2 -2
View File
@@ -286,11 +286,11 @@ if purge and purge_uuid:
print(f"purged: {brain}", flush=True)
target['agy_conversation_id_own'] = None
elif agent == 'hermes':
json_file = f"{home}/.hermes/sessions/session_{purge_uuid}.json"
json_file = f"{home}/.mam/sessions/session_{purge_uuid}.json"
if os.path.exists(json_file):
os.remove(json_file)
print(f"purged: {json_file}", flush=True)
hdb = f"{home}/.hermes/state.db"
hdb = f"{home}/.mam/state.db"
if os.path.exists(hdb):
try:
import sqlite3