basemind-hermes-plugin 0.21.1__tar.gz

basemind_hermes_plugin-0.21.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: basemind-hermes-plugin
+Version: 0.21.1
+Summary: Hermes Agent plugin for basemind — helper skills, slash commands, and agent-comms notifications over the basemind MCP server.
+Author-email: Na'aman Hirschfeld <nhirschfeld@gmail.com>
+License: MIT
+Project-URL: Homepage, https://basemind.ai
+Project-URL: Documentation, https://basemind.ai
+Project-URL: Repository, https://github.com/Goldziher/basemind.git
+Project-URL: Issues, https://github.com/Goldziher/basemind/issues
+Keywords: mcp,hermes,agent-context,code-map,plugin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# basemind-hermes-plugin
+
+The [Hermes Agent](https://github.com/NousResearch/hermes) plugin for
+[basemind](https://github.com/Goldziher/basemind). It adds what MCP config alone cannot: basemind's
+helper **skills**, **slash commands**, and agent-comms **notifications** (session-start context +
+per-turn inbox deltas).
+
+This package is pure-Python and stdlib-only. It does **not** install the `basemind` binary — install
+that separately (see below). The plugin reaches basemind by shelling out to `basemind` on your
+`PATH`, and every hook is fail-open: with no binary or a down comms broker it degrades to a no-op.
+
+## Prerequisites
+
+1. **The `basemind` binary on your `PATH`** — via any channel:
+
+   | Channel | Command |
+   |---|---|
+   | Homebrew | `brew install Goldziher/tap/basemind` |
+   | npm | `npm install -g basemind` |
+   | cargo | `cargo install basemind --features full --locked` |
+   | GitHub releases | [download a binary](https://github.com/Goldziher/basemind/releases) |
+
+2. **The basemind MCP server wired into Hermes** — this is what gives Hermes the 60+ tools. Add to
+   `~/.hermes/config.yaml`:
+
+   ```yaml
+   mcp_servers:
+     basemind:
+       command: basemind
+       args: [serve]
+   ```
+
+## Install the plugin
+
+Install into the **same Python environment Hermes runs in** (Hermes discovers plugins through the
+`hermes_agent.plugins` entry point):
+
+```bash
+pip install basemind-hermes-plugin
+```
+
+Then enable it (general plugins are opt-in):
+
+```bash
+hermes plugins enable basemind
+```
+
+Restart your Hermes session so it re-reads the config and loads the plugin.
+
+## What it registers
+
+- **Skills** — `basemind`, `basemind-code-search`, `basemind-git-history`, `basemind-documents`,
+  `basemind-comms`, `basemind-cli`, `basemind-doctor`, `basemind-scan`, `basemind-stats`.
+- **Slash commands** — `bm`, `bm-init`, `bm-scan`, `bm-doctor`, `bm-stats`, `bm-statusline`.
+- **Hooks** — `on_session_start` (operating discipline + condensed comms inbox) and `pre_llm_call`
+  (per-turn agent-comms deltas). Best-effort; the MCP tools work regardless.
+
+## License
+
+MIT

basemind_hermes_plugin-0.21.1/README.md

@@ -0,0 +1,60 @@
+# basemind-hermes-plugin
+
+The [Hermes Agent](https://github.com/NousResearch/hermes) plugin for
+[basemind](https://github.com/Goldziher/basemind). It adds what MCP config alone cannot: basemind's
+helper **skills**, **slash commands**, and agent-comms **notifications** (session-start context +
+per-turn inbox deltas).
+
+This package is pure-Python and stdlib-only. It does **not** install the `basemind` binary — install
+that separately (see below). The plugin reaches basemind by shelling out to `basemind` on your
+`PATH`, and every hook is fail-open: with no binary or a down comms broker it degrades to a no-op.
+
+## Prerequisites
+
+1. **The `basemind` binary on your `PATH`** — via any channel:
+
+   | Channel | Command |
+   |---|---|
+   | Homebrew | `brew install Goldziher/tap/basemind` |
+   | npm | `npm install -g basemind` |
+   | cargo | `cargo install basemind --features full --locked` |
+   | GitHub releases | [download a binary](https://github.com/Goldziher/basemind/releases) |
+
+2. **The basemind MCP server wired into Hermes** — this is what gives Hermes the 60+ tools. Add to
+   `~/.hermes/config.yaml`:
+
+   ```yaml
+   mcp_servers:
+     basemind:
+       command: basemind
+       args: [serve]
+   ```
+
+## Install the plugin
+
+Install into the **same Python environment Hermes runs in** (Hermes discovers plugins through the
+`hermes_agent.plugins` entry point):
+
+```bash
+pip install basemind-hermes-plugin
+```
+
+Then enable it (general plugins are opt-in):
+
+```bash
+hermes plugins enable basemind
+```
+
+Restart your Hermes session so it re-reads the config and loads the plugin.
+
+## What it registers
+
+- **Skills** — `basemind`, `basemind-code-search`, `basemind-git-history`, `basemind-documents`,
+  `basemind-comms`, `basemind-cli`, `basemind-doctor`, `basemind-scan`, `basemind-stats`.
+- **Slash commands** — `bm`, `bm-init`, `bm-scan`, `bm-doctor`, `bm-stats`, `bm-statusline`.
+- **Hooks** — `on_session_start` (operating discipline + condensed comms inbox) and `pre_llm_call`
+  (per-turn agent-comms deltas). Best-effort; the MCP tools work regardless.
+
+## License
+
+MIT

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/__init__.py

@@ -0,0 +1,8 @@
+"""basemind-hermes-plugin: Hermes Agent plugin for basemind (skills, slash commands, comms hooks)."""
+
+__version__ = "0.21.1"
+
+try:
+    from .hermes import register  # noqa: F401
+except Exception:  # pragma: no cover - defensive: never break plugin load
+    pass

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm-doctor.md

@@ -0,0 +1,34 @@
+---
+name: bm-doctor
+description: Diagnose and recover basemind when it isn't working (MCP tools missing/erroring, "no index", dead server) — runs CLI checks and gives the client-specific way to reconnect the server.
+---
+
+# bm-doctor — diagnose and recover basemind
+
+Diagnose and recover basemind using the CLI (works even with no MCP server running).
+
+## When to use
+
+basemind isn't behaving: MCP tools are missing or erroring, the statusline or a tool reports
+"no index" / "no indexed files", results are empty when they shouldn't be, or the `basemind
+serve` MCP server seems dead.
+
+## How to use
+
+Invoke `/bm-doctor` (optional free-text detail, e.g. `/bm-doctor tools return no indexed files`).
+It runs the checks below in order:
+
+1. Check the index: `basemind query status`.
+2. Check for a lock-holding server: `cat .basemind/.lock.meta`.
+3. Rebuild the index if needed: `basemind scan`.
+4. Reconnect the MCP server (client-specific — this is the only way to restart it).
+
+## Notes
+
+- A stdio MCP server can't be restarted by an agent or by basemind itself; reconnecting it is
+  the MCP client's job. The CLI stays usable throughout.
+
+## See also
+
+The `basemind-doctor` skill for the full step-by-step diagnostic workflow, lock-holder detection,
+and log-reading guidance.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm-init.md

@@ -0,0 +1,57 @@
+---
+name: bm-init
+description: Onboard (or refresh) basemind in this repo — write basemind.toml, gitignore the cache, and inject a "prefer basemind over grep/read/git" rules block into CLAUDE.md / AGENTS.md / ai-rulez.
+argument-hint: [capabilities…]
+---
+
+# bm-init — onboard basemind into this repo
+
+Run `basemind init` so the repo has a committed `basemind.toml`, a gitignored `.basemind/` cache,
+and a rules block that tells every agent to prefer basemind's MCP tools over grep, file reads, and
+naked `git`. CLI and slash command share ONE implementation — this just drives `basemind init`
+with the right non-interactive flags.
+
+## When to use
+
+First time setting up basemind in a repo, or to refresh the rules block after enabling new
+capabilities (documents/RAG, agent-comms, semantic search). Safe to re-run: it's idempotent.
+
+## How to use
+
+1. **Ask which capabilities matter** (one short question). The options are:
+   `code-search-navigation`, `code-mapping-architecture`, `git-history`, `agent-comms`,
+   `documents-rag`, `semantic-search`. If the user has no preference, enable all.
+
+2. **Run `basemind init` non-interactively** with the matching flags. Enable everything:
+
+   ```sh
+   basemind init --yes
+   ```
+
+   Narrow to a subset with repeatable `--with` (allow-list) or `--without` (subtract):
+
+   ```sh
+   basemind init --yes --with code-search-navigation --with git-history
+   ```
+
+   Steer where the rules land with `--rules-target <auto|claude|agents|ai-rulez|none>` (default
+   `auto`). Preview without writing using `--print`.
+
+3. **Report what changed** — which files were written or kept (`basemind.toml`, `.gitignore`, the
+   rules file), and whether the delimited block was created or updated in place.
+
+## Notes
+
+- Source-of-truth detection (auto): `.ai-rulez/config.toml` present → writes
+  `.ai-rulez/rules/basemind-usage.md` (then tell the user to run `ai-rulez generate`; do NOT run
+  it for them). Else CLAUDE.md → AGENTS.md → create CLAUDE.md, wrapping the content in an
+  idempotent `<!-- BEGIN basemind … -->` … `<!-- END basemind -->` block that is replaced in
+  place on re-run, never duplicated. Content outside the markers is never touched.
+- An existing `basemind.toml` is kept verbatim, never clobbered.
+- If `basemind` isn't on `PATH`: use the plugin-managed cache binary or build a dev binary with
+  `cargo build --release` and use `./target/release/basemind`.
+
+## See also
+
+The `bm-scan` command to build the index next, and the `basemind` skill for the full MCP tool
+surface the rules block advertises.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm-scan.md

@@ -0,0 +1,38 @@
+---
+name: bm-scan
+description: Build or refresh the basemind index by running `basemind scan` via the CLI — works without the MCP server (use it when basemind reports "no index" / "no indexed files").
+argument-hint: [path]
+---
+
+# bm-scan — build or refresh the basemind index
+
+Run `basemind scan` via the CLI so the code map exists and is current.
+
+## When to use
+
+basemind (or its statusline) reports "no index" / "no indexed files", an MCP tool returns empty
+results that shouldn't be empty, or the index is stale after large changes.
+
+## How to use
+
+```sh
+basemind scan ${ARGUMENTS:-}
+```
+
+- No argument → full working-tree scan.
+- A path argument (`/bm-scan src/mcp`) → scope the scan to that path (incremental).
+- If `basemind` isn't on `PATH`: use the plugin-managed cache
+  (`${XDG_CACHE_HOME:-~/.cache}/basemind/bin/<version>/basemind`), or build a dev binary with
+  `cargo build --release` and use `./target/release/basemind`.
+
+## Notes
+
+- Report files scanned / updated / skipped and elapsed time. Non-extractable files are
+  **skipped**, not failures.
+- If a `basemind serve` MCP server already holds the store lock for this repo, `scan` errors on
+  the lock — use the `rescan` MCP tool instead, or stop the server first.
+
+## See also
+
+The `basemind-scan` skill for the full workflow, binary-resolution order, and `extra_roots`
+config for indexing directories outside the repo.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm-stats.md

@@ -0,0 +1,43 @@
+---
+name: bm-stats
+description: Show the basemind dashboard — resource footprint (disk + RAM) and activity (tool calls, per-tool histogram, estimated tokens saved). Works with or without the MCP server.
+argument-hint: [today|1h|24h|all]
+---
+
+# bm-stats — basemind dashboard
+
+Show a basemind dashboard with two sections: resource footprint (on-disk size + process RAM) and
+activity (tool calls, per-tool histogram, estimated tokens saved).
+
+## When to use
+
+The user asks "how much is basemind helping?", "show me basemind stats", or wants to check disk /
+RAM usage.
+
+## How to use
+
+Invoke `/bm-stats` (default window `today`) or `/bm-stats <today|1h|24h|all>`. Window: $ARGUMENTS
+
+1. **Resource footprint.** MCP tool `cache_stats`, or CLI `basemind cache stats` (add `--json` to
+   parse). Report: `total_bytes` (matches `du`), the per-component breakdown (blobs / views /
+   git-history / lance / git-cache / telemetry / other), and process RAM (`rss_bytes` +
+   `peak_rss_bytes`). If `blob_accounting_ok` is `false`, note that orphan accounting was skipped
+   (stale/unreadable index — re-scan to restore it); the sizes are still accurate.
+
+2. **Activity.** MCP tool `telemetry_summary`, or CLI `basemind telemetry --window <today|1h|24h|all>`
+   (add `--json`). Report call count, the per-tool histogram, and estimated tokens saved for the
+   window.
+
+3. **Render** both sections as a compact markdown dashboard.
+
+## Notes
+
+- Prefer the MCP tools when connected, but don't depend on them — the CLI reads the same data
+  with no server. If a step's MCP tool isn't available, run its CLI equivalent instead of giving up.
+- If neither MCP nor CLI is reachable, say so plainly and point at `/bm-doctor`.
+- Always end with a one-sentence disclosure that the savings number is heuristic: tools without a
+  realistic baseline (memory, document search, git wrappers) report 0 saved.
+
+## See also
+
+The `basemind-stats` skill for the render shape and the `--explain` breakdown.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm-statusline.md

@@ -0,0 +1,57 @@
+---
+name: bm-statusline
+description: Enable the basemind status line in your Claude Code user settings (one-time setup).
+---
+
+# bm-statusline — enable the basemind status line
+
+Wire the basemind status line into the user's global Claude Code settings, then confirm it
+renders.
+
+## When to use
+
+Run this once per machine to enable the basemind status line in Claude Code. Re-run only if the
+bar goes blank after an unusual settings edit.
+
+## How to use
+
+Invoke `/bm-statusline`. Use your tools to do this directly — do not ask the user to hand-edit
+any files.
+
+1. **Confirm the plugin is installed.** Check that at least one of these exists:
+   - `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/statusline.sh` (if that var is set)
+   - `~/.claude/plugins/marketplaces/basemind/.claude-plugin/statusline.sh`
+   - a match of
+     `~/.claude/plugins/cache/basemind/basemind/*/.claude-plugin/statusline.sh`
+
+   If none exists, tell the user the basemind plugin isn't installed and stop.
+
+2. **Update `~/.claude/settings.json`** (treat a missing file as `{}`). Set its
+   `statusLine` key to this **version-independent resolver** — do NOT hardcode a
+   version-pinned path, which breaks on the next basemind update when the old
+   version dir is pruned:
+
+   ```json
+   { "type": "command",
+     "command": "bash -c 's=$(ls -d \"$HOME\"/.claude/plugins/cache/basemind/basemind/*/.claude-plugin/statusline.sh 2>/dev/null | sort -V | tail -1); [ -f \"$s\" ] || s=\"$HOME/.claude/plugins/marketplaces/basemind/.claude-plugin/statusline.sh\"; [ -f \"$s\" ] && exec bash \"$s\" || printf \"%s\" \"◆ basemind: run /bm-statusline\"'",
+     "refreshInterval": 5 }
+   ```
+
+   How it resolves, in order: the **highest-versioned** cached copy (`sort -V`, not
+   mtime — an older dir touched more recently must never win; this also makes the bar
+   track the newest version the moment `/plugin update` installs it), else the
+   marketplace clone, else a one-line hint so the bar is never blank. It re-resolves
+   at every render, so version bumps never break it and script improvements land
+   automatically. Copy the `command` string
+   **verbatim** (it self-resolves — `$HOME` is expanded by the `bash -c` it runs
+   under, not the settings field). Preserve every other key and verify the file is
+   still valid JSON afterward.
+
+3. **Confirm it renders** by running the resolver once:
+
+   ```bash
+   printf '{"workspace":{"current_dir":"%s"}}' "$PWD" | bash -c 's=$(ls -d "$HOME"/.claude/plugins/cache/basemind/basemind/*/.claude-plugin/statusline.sh 2>/dev/null | sort -V | tail -1); [ -f "$s" ] || s="$HOME/.claude/plugins/marketplaces/basemind/.claude-plugin/statusline.sh"; [ -f "$s" ] && exec bash "$s" || printf "%s" "◆ basemind: run /bm-statusline"'
+   ```
+
+4. Tell the user it's enabled, and that any other running sessions need a
+   relaunch to pick it up.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/commands/bm.md

@@ -0,0 +1,47 @@
+---
+name: bm
+description: Ask basemind anything about the current codebase — outlines, refs, callers, git history, blame, diffs, docs, memory.
+argument-hint: <question about the codebase>
+---
+
+# bm — ask basemind anything about this codebase
+
+Answer the user's question using the basemind MCP server instead of reading files or shelling
+out to grep/git.
+
+## When to use
+
+Invoke with a natural-language question about this repo's code, history, or documents —
+`/bm <question>`. Use it instead of manually picking a tool when you just want an answer.
+
+## How to use
+
+```text
+/bm where is MapCache defined?
+/bm what calls process_file?
+/bm who last touched src/scanner.rs?
+```
+
+Route the question to the tool that answers it directly:
+
+| Example question | Tool |
+|---|---|
+| "Where is X defined?" | `search_symbols` |
+| "What calls X?" | `find_references` (any name) or `find_callers` (specific def) |
+| "What's the shape of this file?" | `outline` (add `l2: true` for calls + docs) |
+| "What changed recently?" | `recent_changes`, `commits_touching`, `symbol_history` |
+| "Who last touched this?" | `blame_file` / `blame_symbol` |
+| "Where's the churn?" | `hot_files` |
+| "Search PDFs/docs in the repo by meaning?" | `search_documents` |
+| "Recall something remembered earlier?" | `memory_get` / `memory_list` / `memory_search` |
+| "Remember this for later sessions?" | `memory_put` (delete with `memory_delete`) |
+| "Refresh the index after editing code?" | `rescan` (pass `paths: [...]` to limit the scope) |
+
+## Notes
+
+- Answer with paths, line numbers, and signatures — read whole files only after a tool has
+  located the exact span you need.
+
+## See also
+
+The `basemind` skill for the full tool-routing table and context-economy discipline.

basemind_hermes_plugin-0.21.1/basemind_hermes_plugin/hermes.py

@@ -0,0 +1,246 @@
+"""Hermes Agent plugin registration for basemind.
+
+basemind's tools reach Hermes through an MCP server declared in ``~/.hermes/config.yaml``
+(``mcp_servers.basemind``) — a Hermes plugin cannot declare an MCP server. This module adds
+what MCP config cannot: the basemind helper *skills*, *slash commands*, and agent-comms
+*notifications* (parity with the Gemini/OpenCode plugin surfaces).
+
+Design constraints (all load-bearing):
+
+* **stdlib-only** — the same package is imported by the ``basemind`` CLI, so this module must
+  not pull in Hermes or any third-party dependency at import time.
+* **import-cheap and side-effect-free** at module load.
+* **fail-open** — every registration and every hook is guarded; a missing ``basemind`` binary,
+  a down comms broker, or a Hermes build that lacks a given ``ctx`` method must degrade to a
+  no-op, never raise. A raising plugin would break both Hermes startup and the CLI.
+
+Hermes calls :func:`register` with a ``PluginContext`` once, at load. The comms hooks close over
+that context so they can call ``ctx.inject_message(...)`` when they fire.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+_PKG_DIR = Path(__file__).resolve().parent
+_SKILLS_DIR = _PKG_DIR / "skills"
+_COMMANDS_DIR = _PKG_DIR / "commands"
+
+_DISCIPLINE = (
+    "basemind is available over MCP in this session — a tree-sitter code map + git context. "
+    "Prefer it over grep/read for structural and historical questions: its tools return paths, "
+    "line numbers, and signatures, not file bodies, so they cost a fraction of the tokens of "
+    "reading source. Default workflow: outline a file before opening it (then read only the span "
+    "you need); search_symbols instead of grep for a definition; find_references/find_callers "
+    "instead of grepping call sites; workspace_grep instead of shelling out to ripgrep; rescan "
+    "after edits instead of reconnecting. Do not re-read a file basemind already mapped."
+)
+
+_COMMS_TOOLS = (
+    "basemind first, shell/grep/git fallback — prefer basemind over grep, over naked git, and for "
+    "docs/RAG/NER, web crawl, and parsing. You are connected to basemind agent-comms — a shared "
+    "multi-agent chat. You have auto-joined every room scoped to this workspace. Levers: room_post "
+    "{room, subject, body, reply_to?} to send (always give a short subject; the body holds the "
+    "detail); room_history {room} and inbox_read to scan messages (these return front-matter only — "
+    "subject/from/id — never bodies, to stay token-frugal); message_get {message_id} to read one "
+    "body on demand; room_list to see rooms, room_join to join another. Prefer posting a concise "
+    "status/question over staying silent when collaborating."
+)
+
+
+def register(ctx) -> None:
+    """Register basemind's skills, slash commands, and comms hooks with Hermes.
+
+    Each capability group is independently guarded so a failure in one (or a ``ctx`` that
+    lacks a given ``register_*`` method) never prevents the others from registering.
+    """
+    for step in (_register_skills, _register_commands, _register_hooks):
+        try:
+            step(ctx)
+        except Exception:  # pragma: no cover - defensive: never break plugin load
+            pass
+
+
+def _register_skills(ctx) -> None:
+    reg = getattr(ctx, "register_skill", None)
+    if not callable(reg) or not _SKILLS_DIR.is_dir():
+        return
+    for skill_md in sorted(_SKILLS_DIR.glob("*/SKILL.md")):
+        _safe_call(reg, skill_md.parent.name, str(skill_md))
+
+
+def _register_commands(ctx) -> None:
+    reg = getattr(ctx, "register_command", None)
+    if not callable(reg) or not _COMMANDS_DIR.is_dir():
+        return
+    for cmd_md in sorted(_COMMANDS_DIR.glob("*.md")):
+        body = _read_text(cmd_md)
+        if not body:
+            continue
+        name = cmd_md.stem
+        description = _front_matter_description(body) or f"basemind {name} command"
+        _safe_call(reg, name, _make_command_handler(body), description)
+
+
+def _make_command_handler(body: str):
+    """A command handler returns the command's markdown (its agent instructions) verbatim.
+
+    These ``.md`` files are the same prompt definitions the Claude/Codex plugins expand, so
+    returning the body gives Hermes faithful slash-command parity without shelling anything.
+    """
+
+    def handler(_args: str = "") -> str:
+        return body
+
+    return handler
+
+
+def _register_hooks(ctx) -> None:
+    reg = getattr(ctx, "register_hook", None)
+    inject = getattr(ctx, "inject_message", None)
+    if not callable(reg) or not callable(inject):
+        return
+
+    def _inject(text):
+        if not text:
+            return
+        if not _safe_call(inject, text):
+            _safe_call(inject, text, "user")
+
+    def on_session_start(**_kwargs):
+        _inject(_session_start_context(os.getcwd()))
+
+    def pre_llm_call(**kwargs):
+        sid = str(kwargs.get("task_id") or kwargs.get("session_id") or "default")
+        _inject(_delta_context(os.getcwd(), sid))
+
+    _safe_call(reg, "on_session_start", on_session_start)
+    _safe_call(reg, "pre_llm_call", pre_llm_call)
+
+
+def _session_start_context(cwd: str) -> str:
+    """Boot context: the operating discipline, plus a condensed comms inbox if the broker responds."""
+    messages = _inbox_messages(cwd, 8)
+    if messages is None:
+        return _DISCIPLINE
+    if messages:
+        return (
+            f"{_DISCIPLINE} {_COMMS_TOOLS}\n"
+            "Recent messages (front-matter only; call message_get with an id to read a body):\n"
+            f"{_format_lines(messages)}"
+        )
+    return f"{_DISCIPLINE} {_COMMS_TOOLS} No messages in your rooms yet — post one to kick things off."
+
+
+def _delta_context(cwd: str, session_id: str) -> str | None:
+    """Per-turn delta: inject only messages newer than this session's high-water mark."""
+    messages = _inbox_messages(cwd, 30)
+    if not messages:
+        return None
+    max_ts = max((_ts(m) for m in messages), default=0)
+    hwm_file = _hwm_path(session_id)
+    if not hwm_file.exists():
+        _write_text(hwm_file, str(max_ts))
+        return None
+    hwm = _read_int(hwm_file)
+    fresh = [m for m in messages if _ts(m) > hwm]
+    if not fresh:
+        return None
+    _write_text(hwm_file, str(max_ts))
+    return (
+        "New basemind agent-comms message(s) since your last turn (front-matter only — call "
+        "message_get with an id to read a body):\n"
+        f"{_format_lines(fresh)}\n"
+        "Reply with room_post {room, subject, body, reply_to:<id>} if a response is warranted."
+    )
+
+
+def _inbox_messages(cwd: str, limit: int):
+    """Return the inbox message list (possibly empty), or ``None`` when the broker is unavailable."""
+    data = _run_basemind_json(["comms", "inbox", "--root", cwd, "--json", "--limit", str(limit)], timeout=6)
+    if data is None:
+        return None
+    messages = data.get("messages")
+    return messages if isinstance(messages, list) else []
+
+
+def _run_basemind_json(args, timeout):
+    try:
+        proc = subprocess.run(  # noqa: S603,S607 - fixed argv, no shell
+            ["basemind", *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        return json.loads(proc.stdout)
+    except Exception:
+        return None
+
+
+def _format_lines(messages) -> str:
+    return "\n".join(f"  • [{m.get('subject', '')}] from {m.get('from', '')} (id: {m.get('id', '')})" for m in messages)
+
+
+def _ts(message) -> int:
+    try:
+        return int(message.get("ts_micros") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _hwm_path(session_id: str) -> Path:
+    safe = "".join(c if (c.isalnum() or c in "._-") else "_" for c in session_id) or "default"
+    return Path(tempfile.gettempdir()) / f"basemind-comms-hwm-{safe}"
+
+
+def _front_matter_description(body: str) -> str | None:
+    """Pull ``description:`` from a leading ``---`` YAML front-matter block, if present."""
+    if not body.startswith("---"):
+        return None
+    end = body.find("\n---", 3)
+    if end == -1:
+        return None
+    for line in body[3:end].splitlines():
+        stripped = line.strip()
+        if stripped.startswith("description:"):
+            return stripped[len("description:") :].strip().strip("\"'") or None
+    return None
+
+
+def _safe_call(fn, *args) -> bool:
+    """Call ``fn(*args)``; return True on success, False on any exception. Never raises."""
+    try:
+        fn(*args)
+        return True
+    except Exception:
+        return False
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+def _write_text(path: Path, text: str) -> None:
+    try:
+        path.write_text(text, encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _read_int(path: Path) -> int:
+    try:
+        return int(path.read_text(encoding="utf-8").strip() or "0")
+    except Exception:
+        return 0