downbeat 0.1.1__py3-none-any.whl

downbeat/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

downbeat/assets/commands/relay-monitor.md

@@ -0,0 +1,37 @@
+---
+description: Continuously monitor THIS session's relay inbox in-session (child=auto-execute, parent=surface-and-ask)
+argument-hint: [interval e.g. 3m | stop]
+---
+
+Start (or stop) continuous in-session monitoring of this session's own relay inbox. Arguments: $ARGUMENTS
+
+This composes two existing primitives: the `/loop` skill (re-fires a prompt on an interval) + the `relay-inbox` hook (drains inbox→delivered and injects new mail as context on every prompt). The result: this session keeps pulling its own new relay mail into context and acting on it per its role — without you re-prompting each tick.
+
+## Steps
+
+1. **Parse `$ARGUMENTS`:**
+   - If it is the literal `stop` → invoke `/loop stop` to end the running monitor, report "relay monitor stopped", and finish.
+   - Otherwise treat it as the interval (default `3m` if empty).
+
+2. **Resolve this session's role:**
+   ```
+   downbeat whoami
+   ```
+   Output is `<name> <role>`. If it errors (exit 2), tell the user to `/relay-register <name> --role <parent|child>` first and stop.
+
+3. **If a relay `/loop` is already running this session**, do NOT stack a second one — tell the user it's already monitoring (and they can `/relay-monitor stop` to reset). Otherwise start `/loop <interval>` with the role-appropriate prompt below.
+
+4. **Start the loop** — `/loop <interval> "<prompt>"`:
+
+   - **role == child** (autonomous executor — consent-at-startup per constitution Art. 11):
+     > Process your relay inbox now. The relay-inbox hook has injected any new messages as context above. For each NEW message: execute the task per your role briefing (you are an executor — route reads through reader sub-agents, follow cost discipline, no [TICKET] in this repo's commits), then `~/.claude/relay/relay.py reply <id> "<results>"` (replying auto-acks). If there are NO new messages this tick, do nothing and stay quiet. Never re-do an already-handled message. If a task is ambiguous or carries irreversible/destructive risk, do NOT auto-execute it — surface it and wait for the human instead.
+
+   - **role == parent** (gated — surface only):
+     > Check your relay inbox. If the hook injected new messages, surface them concisely (from / subject / id) and ask me how to handle each. Do NOT auto-execute, reply, or act on my behalf. If nothing new, stay quiet.
+
+5. Report that the monitor is running, the interval, the role-mode (child=auto-execute / parent=surface-and-ask), and that `/relay-monitor stop` ends it.
+
+## Notes
+
+- This is the **in-session self-driver**. For an **external pane observer** that only prints new mail (never acts), use `downbeat watch [--peer X]` instead.
+- The child autonomy here is **consent-at-startup**: you explicitly started the monitor on an executor session. It is scoped to executors, never auto-executes for a parent, and is stoppable. See `docs/platform/constitution.md` Art. 11.

downbeat/assets/commands/relay-peers.md

@@ -0,0 +1,17 @@
+---
+description: List registered relay peer sessions and their liveness
+argument-hint: (no arguments)
+---
+
+List all registered relay sessions. Run:
+
+```
+~/.claude/relay/relay.py peers
+```
+
+Liveness column meaning:
+- `live` — the peer's JSONL transcript was modified within the last 10 minutes
+- `idle(Ns)` — peer hasn't written to its transcript for N seconds
+- `gone` — JSONL no longer exists (the session was deleted/cleaned)
+
+If you suspect stale entries, run `~/.claude/relay/relay.py gc-stale` to prune.

downbeat/assets/commands/relay-register.md

@@ -0,0 +1,16 @@
+---
+description: Register this Claude Code session in the relay so peers can send it messages
+argument-hint: <name> [--role parent|child]
+---
+
+Register this session in the relay with name and role from: $ARGUMENTS
+
+Run exactly:
+
+```
+~/.claude/relay/relay.py register $ARGUMENTS
+```
+
+If the user provided no `--role`, the CLI defaults to `child`.
+
+Report the CLI's output back verbatim. Do not retry on failure — surface the error to the user.

downbeat/assets/commands/relay-reply.md

@@ -0,0 +1,36 @@
+---
+description: Reply to a relay message you previously received
+argument-hint: <msg_id> <body...>
+---
+
+Reply to a previously received relay message. Arguments: $ARGUMENTS
+
+## If `$ARGUMENTS` is EMPTY — treat this as an INBOX CHECK, not a reply
+
+A bare `/relay-reply` (no `<msg_id>`) is the user's inbox-check shortcut. Do this:
+
+1. Look at the CURRENT turn's context for a `### Relay inbox — N new message(s)` banner (the hook drains the inbox into context on each prompt). That block IS your pending mail.
+2. If none is in context, verify directly: `downbeat whoami` for your peer name, then check `~/.claude/relay/inbox/<me>/` and `~/.claude/relay/delivered/<me>/` for `.json` files.
+3. **If there ARE pending messages** (especially from the parent) → surface them and reply/handle as appropriate (fall through to the reply flow below with the real `<msg_id>`).
+4. **If there are NONE → SKIP. Take no action.** Do not fabricate a reply, do not invent a `<msg_id>`, and do NOT send proactive/unsolicited messages to the parent. Just report "inbox empty, nothing to reply to" and stop.
+
+## If `$ARGUMENTS` has a msg_id + body — reply normally
+
+Parse `$ARGUMENTS` as: `<msg_id> <body...>` where `<msg_id>` is the 16-char hex id from a message in your inbox (look at the most recent relay message context), and the rest is the reply body.
+
+If the body is long or multi-line:
+
+```
+~/.claude/relay/relay.py reply <msg_id> "$(cat <<'EOF'
+<body>
+EOF
+)"
+```
+
+Otherwise:
+
+```
+~/.claude/relay/relay.py reply <msg_id> "<body>"
+```
+
+The reply is routed to the original sender's inbox using the `from` field of the message stored under `~/.claude/relay/processed/<your_name>/<msg_id>.json`. If the CLI errors with "msg_id not found", the message was either never received here or already replied to in a way that moved it.

downbeat/assets/commands/relay-send.md

@@ -0,0 +1,25 @@
+---
+description: Send a relay message to a peer Claude Code session
+argument-hint: <to> <subject> <body...>
+---
+
+Send a relay message. Arguments: $ARGUMENTS
+
+Parse `$ARGUMENTS` as: `<to> <subject> <body...>` where `<to>` is the peer name, `<subject>` is a single token (use quotes if multi-word), and everything after is the body.
+
+If the body is long or multi-line, write it to a temp file first and pass via shell substitution:
+
+```
+~/.claude/relay/relay.py send <to> "<subject>" "$(cat <<'EOF'
+<body>
+EOF
+)"
+```
+
+Otherwise call directly:
+
+```
+~/.claude/relay/relay.py send <to> "<subject>" "<body>"
+```
+
+Report the CLI's output (it includes the message id). The peer will receive the message on their next prompt or session start, prepended as system context by the `relay-inbox` hook.

downbeat/assets/hooks/relay-inbox.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Relay inbox hook — drains pending messages into additionalContext.
+
+Wired into:
+  UserPromptSubmit  — runs before every user prompt is processed
+  SessionStart      — runs when a session starts/resumes (picks up offline mail)
+
+Behavior:
+  1. Read the hook payload (JSON on stdin) → session_id
+  2. Reverse-lookup session_id in ~/.claude/relay/sessions.json → peer name
+  3. If unregistered, silent no-op (zero impact on non-relay sessions)
+  4. List ~/.claude/relay/inbox/<name>/*.json sorted by mtime
+  5. For each message, read body, accumulate into a single markdown block
+  6. Stamp `delivered_at` + `delivered_to_session_id` on each message and
+     atomically move it to delivered/<name>/<id>.json (NOT processed/ —
+     that's the v0.2 two-phase delivery state machine; messages need an
+     ack OR a matching reply OR a TUI archive to promote to processed/).
+  7. Emit hookSpecificOutput.additionalContext
+
+Fails open: any exception → stderr + exit 0, never blocks.
+"""
+
+import json
+import re
+import sys
+import tempfile
+import traceback
+from datetime import UTC, datetime
+from pathlib import Path
+
+RELAY_DIR = Path.home() / ".claude" / "relay"
+SESSIONS_FILE = RELAY_DIR / "sessions.json"
+INBOX_DIR = RELAY_DIR / "inbox"
+DELIVERED_DIR = RELAY_DIR / "delivered"
+
+MAX_MESSAGES_PER_DRAIN = 20  # safety cap
+
+# Phase 2: backflow-relay rendering.
+# BACKFLOW_KIND must match the literal used in the downbeat SKILL.md and
+# command texts — defined ONCE here (the only Python consumer). NEVER the
+# underscore variant.
+BACKFLOW_KIND = "backflow-ready"
+BACKFLOW_FENCE_RE = re.compile(r"```json backflow\s*\n(.*?)```", re.DOTALL)
+
+
+def parse_backflow(body):
+    """Extract the FIRST ```json backflow fence from body.
+
+    Returns (payload, stripped_body). Valid = JSON parses AND has BOTH required
+    keys (proposed_updates_path, findings). Anything else -> (None, body) —
+    callers then decide whether an 'unparsed' note applies (only when the
+    message CLAIMED backflow via kind, or a fence is present but broken).
+    """
+    m = BACKFLOW_FENCE_RE.search(body or "")
+    if not m:
+        return None, body
+    try:
+        payload = json.loads(m.group(1))
+    except Exception:
+        return None, body
+    if (not isinstance(payload, dict)
+            or "proposed_updates_path" not in payload
+            or "findings" not in payload):
+        return None, body
+    stripped = (body[:m.start()] + body[m.end():]).strip()
+    return payload, stripped
+
+
+def _now_iso():
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def name_for_session(session_id, sessions):
+    for name, meta in sessions.items():
+        if meta.get("session_id") == session_id:
+            return name
+    return None
+
+
+def _atomic_write_json(target: Path, payload: dict) -> None:
+    """Write JSON atomically: temp in same dir, then os.replace."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(target.parent), prefix=".tmp-", text=True
+    )
+    import os
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(payload, indent=2))
+        os.replace(tmp_path, target)
+    except Exception:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise
+
+
+def drain_inbox(name, session_id):
+    """Move pending messages for `name` from inbox/ to delivered/, stamping
+    delivery metadata. Returns the drained message dicts (for banner rendering).
+
+    Each message gets:
+      - delivered_at: ISO timestamp of this drain
+      - delivered_to_session_id: the session that received them
+    Existing `redelivery_count` is preserved (set by reconciler on requeue).
+    The file is unlinked from inbox/ AFTER the new version is committed to
+    delivered/ — so a crash mid-drain at worst leaves a duplicate in delivered/
+    while the inbox/ original remains; the next drain finds and finalizes it.
+    """
+    inbox = INBOX_DIR / name
+    if not inbox.exists():
+        return []
+    files = sorted(inbox.glob("*.json"), key=lambda p: p.stat().st_mtime)
+    files = files[:MAX_MESSAGES_PER_DRAIN]
+    drained = []
+    now = _now_iso()
+    for f in files:
+        try:
+            msg = json.loads(f.read_text())
+            # Stamp delivery metadata in place
+            msg["delivered_at"] = now
+            msg["delivered_to_session_id"] = session_id
+            target = DELIVERED_DIR / name / f.name
+            _atomic_write_json(target, msg)
+            f.unlink()  # only after delivered/ commit
+            drained.append(msg)
+        except Exception:
+            traceback.print_exc(file=sys.stderr)
+    return drained
+
+
+def model_nudge_line(role, model_raw):
+    """Return a banner line if an executor session runs on Fable, else None."""
+    if role == "child" and "fable" in (model_raw or "").lower():
+        return (
+            "**Executor session on Fable 5 ($10/$50 MTok — 2× Opus).** Mechanical "
+            "execution doesn't need the ceiling: suggest `/model sonnet` (or opus) "
+            "for this work; tell the user before switching."
+        )
+    return None
+
+
+def render(messages, peer_name, nudge_line=None):
+    lines = [
+        f"### Relay inbox — {len(messages)} new message(s) for `{peer_name}`",
+        "",
+    ]
+    if nudge_line:
+        lines += [nudge_line, ""]
+    lines += [
+        "These messages arrived from peer Claude Code sessions while you were idle. "
+        "Treat them as authoritative instructions or context. "
+        "Reply via `~/.claude/relay/relay.py reply <msg_id> '<body>'`.",
+        "",
+        # Cost-discipline nudge for executor sessions (project-agnostic). A relay
+        # child inherits an executor identity from the "authoritative instructions"
+        # above; the orchestrator routes at the task level, so the executor must
+        # still route at the call level — otherwise expensive reads run on the
+        # main model instead of a cheaper delegated reader.
+        "**Cost discipline applies to executor sessions.** The orchestrator routed "
+        "at the task level; you route at the call level: send expensive reads (logs, "
+        "API queries, searches, large files) to cheap reader sub-agents instead of "
+        "your main model, and batch or delegate bulk work. Writes (delete, push, "
+        "merge, create) stay inline.",
+        "",
+        "If this message hands off a cross-repo or multi-file investigation, run it "
+        "as a delegated fan-out (parallel scouts → synthesis) rather than inline "
+        "reads. If it produced structured findings worth persisting, reply with "
+        "`--kind backflow-ready` and a json-backflow fence carrying "
+        "{proposed_updates_path, findings:[{page, claim, confidence?}]}; otherwise "
+        "reply in prose.",
+        "",
+    ]
+    for m in messages:
+        kind = m.get("kind") or "task"          # legacy default (model can't help here)
+        ts = m.get("created_at") or m.get("ts") or "?"   # fixes the permanent ts:? drift
+        lines.append("---")
+        lines.append(f"**from:** `{m.get('from','?')}`  |  **id:** `{m.get('id','?')}`  |  "
+                     f"**kind:** {kind}  |  **ts:** {ts}")
+        if m.get("in_reply_to"):
+            lines.append(f"**in_reply_to:** `{m['in_reply_to']}`")
+        if m.get("subject"):
+            lines.append(f"**subject:** {m.get('subject')}")
+        lines.append("")
+        payload, stripped_body = parse_backflow(m.get("body", ""))
+        if payload is not None:
+            # Fence content renders for ANY kind (belt-and-suspenders: survives a
+            # kind typo AND works before the CLI gains --kind). kind only adds
+            # the prominent header.
+            if kind == BACKFLOW_KIND:
+                lines.append("### 🔄 BACKFLOW — proposed updates from a delegated run")
+                lines.append("")
+            lines.append(stripped_body or "(no summary)")
+            lines.append("")
+            lines.append(f"**Proposed-updates file:** `{payload['proposed_updates_path']}`")
+            for f_ in payload.get("findings", []):
+                page, claim = f_.get("page", "?"), f_.get("claim", "?")
+                conf = f_.get("confidence")
+                lines.append(f"- `[[{page}]]` — {claim}" + (f" _({conf})_" if conf else ""))
+            lines.append("")
+            # Guard rides with the CONTENT, not the kind (3R-6).
+            lines.append("**Surface these for human triage — do not auto-apply.**")
+        elif kind == BACKFLOW_KIND:
+            # Claimed backflow, couldn't deliver it (fence missing/invalid).
+            lines.append(m.get("body", "(empty)"))
+            lines.append("")
+            lines.append("_(unparsed backflow block — fence missing or invalid)_")
+        else:
+            # Plain message, nothing claimed -> NO backflow note (2R-7).
+            lines.append(m.get("body", "(empty)"))
+        lines.append("")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def emit_context(event_name, text):
+    sys.stdout.write(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": event_name,
+            "additionalContext": text,
+        }
+    }) + "\n")
+    sys.stdout.flush()
+
+
+def main():
+    raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        payload = {}
+
+    session_id = payload.get("session_id")
+    event_name = payload.get("hook_event_name") or "UserPromptSubmit"
+
+    if not session_id:
+        return
+    if not SESSIONS_FILE.exists():
+        return
+
+    try:
+        sessions = json.loads(SESSIONS_FILE.read_text())
+    except Exception:
+        return
+
+    name = name_for_session(session_id, sessions)
+    if not name:
+        return  # unregistered session — silent no-op
+
+    drained = drain_inbox(name, session_id)
+    if not drained:
+        return
+
+    nudge = None
+    try:
+        role = sessions.get(name, {}).get("role")
+        settings_path = Path.home() / ".claude" / "settings.json"
+        model_raw = json.loads(settings_path.read_text()).get("model", "")
+        nudge = model_nudge_line(role, model_raw)
+    except Exception:
+        pass  # fail open — nudge is advisory only
+
+    emit_context(event_name, render(drained, name, nudge_line=nudge))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(0)

downbeat/assets/hooks/relay-poll-offer.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Relay poll-offer hook — PostToolUse on Bash.
+
+After a `send` or `reply` via the relay CLI, inject a one-time system reminder
+asking Claude to consider offering the user a `/loop 3m` inbox-poll setup.
+
+State file: ~/.claude/relay/loop_offer_state.json
+  Keyed by session_id; each entry has {"hinted_at": ISO, "decided": bool}.
+
+Fails open: any exception → stderr + exit 0, never blocks.
+"""
+
+import json
+import re
+import sys
+import traceback
+from datetime import UTC, datetime
+from pathlib import Path
+
+STATE_FILE = Path.home() / ".claude" / "relay" / "loop_offer_state.json"
+
+# Match either path-based shim or the global CLI binary.
+SEND_REPLY_RE = re.compile(
+    r"(?:relay\.py|downbeat)\s+(?:send|reply)\b"
+)
+
+HINT = (
+    "The user just executed a relay `send`/`reply`. If they appear to be done "
+    "with local work for now AND there is no relay `/loop` already running in "
+    "this session, use AskUserQuestion to offer:\n\n"
+    "> \"You just sent a relay message. Want me to check the inbox every 3 "
+    "minutes for a reply and surface it when it arrives?\"\n\n"
+    "Options:\n"
+    "- Yes, poll every 3 min → invoke `/loop 3m Check the relay inbox via "
+    "~/.claude/relay/relay.py inbox. If there are new messages for a "
+    "registered peer, surface them concisely (sender, subject, id) and ask "
+    "how to handle each. If empty, stay silent.`\n"
+    "- Yes, poll every 5 min → same instruction with `/loop 5m`\n"
+    "- No, I'll check manually\n\n"
+    "If the user already has queued tasks or is actively working on something "
+    "else, do NOT interrupt — skip the offer this turn. This hint will only "
+    "fire ONCE per session."
+)
+
+
+def _load_state() -> dict:
+    if not STATE_FILE.exists():
+        return {}
+    try:
+        return json.loads(STATE_FILE.read_text() or "{}")
+    except Exception:
+        return {}
+
+
+def _save_state(data: dict) -> None:
+    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(data, indent=2))
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        # No stdin / not JSON → silent no-op
+        return
+
+    tool_name = payload.get("tool_name") or payload.get("toolName") or ""
+    if tool_name != "Bash":
+        return
+
+    tool_input = payload.get("tool_input") or payload.get("toolInput") or {}
+    command = (tool_input.get("command") or "").strip()
+    if not SEND_REPLY_RE.search(command):
+        return
+
+    # Tool result inspection: only fire if the command succeeded.
+    tool_result = payload.get("tool_result") or payload.get("toolResult") or {}
+    # Exit code field varies; treat absent as success (best-effort).
+    exit_code = tool_result.get("exit_code")
+    if exit_code is not None and exit_code != 0:
+        return
+
+    session_id = (
+        payload.get("session_id")
+        or payload.get("sessionId")
+        or ""
+    )
+    if not session_id:
+        # No session id → still emit the hint (better safe than silent), but
+        # we can't dedupe by session.
+        sys.stdout.write(json.dumps({"systemMessage": HINT}) + "\n")
+        return
+
+    state = _load_state()
+    entry = state.get(session_id) or {}
+    if entry.get("hinted_at"):
+        # Already fired in this session — silent.
+        return
+
+    entry["hinted_at"] = datetime.now(UTC).isoformat(timespec="seconds")
+    state[session_id] = entry
+    try:
+        _save_state(state)
+    except Exception:
+        traceback.print_exc(file=sys.stderr)
+
+    sys.stdout.write(json.dumps({"systemMessage": HINT}) + "\n")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        traceback.print_exc(file=sys.stderr)
+        # Never block tools
+        sys.exit(0)

downbeat/assets/hooks_manifest.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Registration source of truth for `downbeat init`. Mirrors the real ~/.claude/settings.json hook layout: settings['hooks'][<event>] is a list of entries, each {matcher?, hooks:[{type,command,timeout}]}. Relay hooks may live INSIDE a multi-hook entry alongside non-relay hooks (e.g. cost-discipline) — init detects by command-substring and never clobbers neighbours. `command` here is the hook basename; init resolves it to <HOME>/.claude/hooks/<basename>. matcher null means the entry carries no matcher key.",
+  "events": [
+    {"event": "UserPromptSubmit", "matcher": null, "command": "relay-inbox.py", "timeout": 3},
+    {"event": "SessionStart", "matcher": "startup|resume", "command": "relay-inbox.py", "timeout": 3},
+    {"event": "PostToolUse", "matcher": "Bash", "command": "relay-poll-offer.py", "timeout": 3}
+  ]
+}