npm - @delorenj/pjangler - Versions diffs - 1.1.3 - Mend

@delorenj/pjangler 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (898) hide show

package/templates/hermes-agent/docs/scrum-master/providers.md ADDED Viewed

@@ -0,0 +1,203 @@
+# Provider adapters
+This guide is the reference for the ticket-provider abstraction: the contract
+every adapter implements, the three adapters that ship today, and a
+step-by-step process for adding a new provider or verifying an existing one
+against a live board. Read [Architecture](architecture.md) first for how the
+adapter fits into the engine.
+## The contract
+Each adapter is a standalone POSIX shell script under
+`template/.scripts/providers/<name>.sh`. It reads its credentials from the
+environment and its board binding from `role.yaml` under `ticket_provider`. It
+takes an operation as its first argument and writes JSON or a status string to
+standard output.
+The dispatcher, `template/.scripts/lib/ticket-provider.sh`, resolves the active
+provider and routes calls. Source it, then call `tp <operation> [args...]`:
+```bash
+. .scripts/lib/ticket-provider.sh
+tp active_milestone
+tp list_issues
+tp transition DEL-42 completed
+```
+Every adapter must implement these operations.
+| Operation | Arguments | Output |
+| --- | --- | --- |
+| `resolve` | none | JSON `{provider, board_id, board_url}`. Validates credentials and board binding. |
+| `active_milestone` | none | JSON `{id, name, state}` for the current milestone, cycle, or board. |
+| `list_issues` | none | JSON array of `{id, key, title, state, state_type, updated_at, assignee, url}`. |
+| `get_issue` | `<id>` | JSON `{id, key, title, description, acceptance, state, state_type, comments}`. |
+| `comment` | `<id> <body>` | Prints the new comment id. |
+| `transition` | `<id> <normalized-state>` | Moves the issue to a normalized state. |
+| `create_board` | `<name> <ident> <desc>` | JSON `{board_id, board_url}`. Creates or reuses the board. |
+The `transition` operation accepts only the normalized states from
+[Architecture: normalized states](architecture.md#normalized-states):
+`backlog`, `unstarted`, `started`, `in_review`, and `completed`. The adapter
+maps each to its back end's concrete state.
+## The adapters that ship today
+The repository includes three adapters with different verification status.
+- **Linear** (`providers/linear.sh`) is the reference implementation. It uses
+  the Linear GraphQL API. It's verified live against a real board. Linear's
+  `issue(id:)` field accepts both the UUID and the human identifier (for
+  example, `DEL-42`), so the engine can pass identifiers through.
+- **Plane** (`providers/plane.sh`) uses the Plane REST API with `X-API-Key`
+  authentication. A Plane project maps to the board, a cycle maps to the
+  milestone, and `state.group` maps to the state type. It's verified live. Note
+  the v1 API returns an issue's `state` as a bare UUID with no `state_detail`,
+  so the adapter joins each issue against the project's states map; descriptions
+  come from `description_html`.
+- **Trello** (`providers/trello.sh`) uses the Trello REST API with `key` and
+  `token` query-parameter authentication. A board maps to both the project and
+  the milestone, a list maps to the state, and a card maps to the issue. It's
+  implemented but not yet verified against a live board.
+### Credentials and binding by provider
+Set credentials in the environment and the board binding in `role.yaml`.
+<details>
+<summary>Linear</summary>
+- Credentials: `LINEAR_API_KEY`.
+- Binding:
+  ```yaml
+  ticket_provider:
+    name: linear
+    team: DEL # Linear team key
+    project: "" # optional, scopes milestone and issue queries
+  ```
+</details>
+<details>
+<summary>Plane</summary>
+- Credentials: `PLANE_API_KEY`. Endpoint: `PLANE_BASE` (default
+  `https://plane.delo.sh`).
+- Binding:
+  ```yaml
+  ticket_provider:
+    name: plane
+    workspace: <workspace-slug>
+    project: <project-uuid> # set by 42-ticket-provider.sh
+  ```
+</details>
+<details>
+<summary>Trello</summary>
+- Credentials: `TRELLO_KEY` and `TRELLO_TOKEN`.
+- Binding:
+  ```yaml
+  ticket_provider:
+    name: trello
+    board: <board-id> # set by 42-ticket-provider.sh
+    state_map: { backlog: "Backlog", started: "In Progress", completed: "Done" }
+  ```
+</details>
+## Adding a provider
+To add a fourth provider, for example GitHub Issues or Jira, follow these steps.
+1. Create `template/.scripts/providers/<name>.sh`. Start from `linear.sh` if the
+   back end uses GraphQL, or `plane.sh` if it uses REST with a single API key.
+2. Implement every operation in [the contract](#the-contract). Return the exact
+   JSON shapes shown in the table. Map your back end's states to the five
+   normalized states.
+3. Fail fast and clean. Validate credentials at the top of the script, before
+   any pipe, so a missing key prints one error line instead of a stack trace.
+   The existing adapters call a `need_key` helper for this.
+4. Add the provider to the `ticket_provider` question in `copier.yml` so it
+   appears as a choice.
+5. Extend `template/role.yaml.jinja` with a provider-specific binding block
+   under the `{% if ticket_provider == '<name>' %}` branch.
+6. Teach `42-ticket-provider.sh` how to resolve or create the board for your
+   provider, if it differs from the existing `linear`, `plane`, and `trello`
+   cases.
+7. Validate and verify with the steps below.
+<!-- prettier-ignore -->
+> [!WARNING]
+> Don't put escaped double quotes inside a single-quoted `python3 -c '...'`
+> block. A single-quoted shell string keeps backslashes literal, so `\"`
+> reaches Python as a backslash-quote and fails to parse. Use a `python3 -
+> <<'PY'` heredoc, or hoist values into variables, when you need quotes.
+## Validating an adapter offline
+Before you touch a live board, confirm the adapter parses and fails cleanly.
+1. Check shell syntax:
+   ```bash
+   sh -n template/.scripts/providers/<name>.sh
+   ```
+2. Check the inline Python blocks. Extract each `<<'PY'` heredoc and each
+   `python3 -c '...'` block and run it through `python3 -c "import ast;
+   ast.parse(open('block').read())"`, or use the small extraction script in
+   [Development guide: validating
+   locally](development.md#validating-changes-locally).
+3. Confirm a missing credential produces one clean error line and a non-zero
+   exit, with no Python traceback:
+   ```bash
+   ( unset LINEAR_API_KEY; sh template/.scripts/providers/linear.sh resolve )
+   ```
+## Verifying an adapter against a live board
+When you have credentials, exercise the read operations against a real board.
+The following pattern stages a minimal role directory and runs the adapter. It
+never closes or modifies a ticket, so it's safe to run.
+```bash
+# 1. Load the credential into the environment only (never print it).
+export LINEAR_API_KEY="$(grep -E '^(export )?LINEAR_API_KEY=' \
+  ~/.hermes/<agent>.env | head -1 | sed -E 's/^(export )?LINEAR_API_KEY=//; s/^"//; s/"$//')"
+# 2. Stage a role directory bound to the real board.
+T=$(mktemp -d); RD="$T/agents/hermes/scrum-master"
+mkdir -p "$RD/.scripts/lib" "$RD/.scripts/providers"
+cp template/.scripts/lib/ticket-provider.sh "$RD/.scripts/lib/"
+cp template/.scripts/providers/linear.sh "$RD/.scripts/providers/"
+printf 'repo: demo\nrole: scrum-master\nticket_provider:\n  name: linear\n  team: DEL\n' \
+  > "$RD/role.yaml"
+# 3. Run the read operations.
+LIB="$RD/.scripts/lib/ticket-provider.sh"
+bash -c '. "$1"; tp resolve' _ "$LIB"
+bash -c '. "$1"; tp list_issues' _ "$LIB" | python3 -c 'import sys,json; print(len(json.load(sys.stdin)),"issues")'
+```
+To verify `transition` and `comment`, which modify the board, use a disposable
+test ticket. Don't run write operations against production tickets during
+verification.
+<!-- prettier-ignore -->
+> [!NOTE]
+> The dispatcher needs Bash because it reads `${BASH_SOURCE[0]}` to find the
+> providers directory. The adapters themselves are POSIX shell and run under
+> `sh`. Run the dispatcher with `bash -c`, as shown above, not `sh -c`.
+## Read next
+- [Development guide](development.md): the full edit, validate, and propagate
+  workflow, plus the open roadmap, which includes live-verifying Plane and
+  Trello.

package/templates/hermes-agent/docs/scrum-master-sentinel.md ADDED Viewed

@@ -0,0 +1,17 @@
+# Scrum Master role and the ticket sentinel
+The Scrum Master is a Hermes agent role whose core loop is a provider-agnostic
+ticket sentinel with an autonomous adversarial review (act, do not wait). The
+full documentation has moved to a dedicated handoff guide.
+This page is kept as a stable pointer so existing links keep working.
+## Where the docs live now
+- [Scrum Master handoff overview](scrum-master/README.md): start here.
+- [Architecture](scrum-master/architecture.md): the watch loop, the provider
+  abstraction, and the autonomous adversarial review.
+- [Providers](scrum-master/providers.md): the adapter contract and how to add or
+  verify a provider.
+- [Development guide](scrum-master/development.md): editing, validating,
+  provisioning, propagating, the Drumjangler cutover record, and the roadmap.

package/templates/hermes-agent/install-local.sh ADDED Viewed

@@ -0,0 +1,214 @@
+#!/usr/bin/env sh
+# Least-friction local install of Hermes PM + Scrum Master roles into a project.
+#
+# Local-only: no GitHub runtime repo, no Telegram, no NATS/BloodBank, no Plane
+# project creation. It binds the Scrum Master to a ticket board you already have.
+# Works on macOS (launchd) and Linux (systemd).
+#
+# One-liner (from anywhere inside the target project):
+#   curl -fsSL https://raw.githubusercontent.com/delorenj/hermes-agent-template/main/install-local.sh | sh
+#
+# Or from a checkout:
+#   sh /path/to/hermes-agent-template/install-local.sh
+#
+# Environment overrides (skip the prompts):
+#   HAT_REPO=<name>            project/repo name (default: basename of CWD)
+#   HAT_PROVIDER=linear|plane|trello   (default: plane)
+#   HAT_ROLES="pm scrum-master"        roles to install (default: both)
+#   HAT_DRY_RUN=1              print actions, change nothing
+#   Provider creds: LINEAR_API_KEY | PLANE_API_KEY+PLANE_BASE | TRELLO_KEY+TRELLO_TOKEN
+set -eu
+say()  { printf '\033[36m%s\033[0m\n' "$*"; }
+warn() { printf '\033[33m%s\033[0m\n' "$*" >&2; }
+die()  { printf '\033[31m%s\033[0m\n' "$*" >&2; exit 1; }
+run()  { if [ "${HAT_DRY_RUN:-0}" = "1" ]; then printf '  [dry-run] %s\n' "$*"; else eval "$*"; fi; }
+ask()  { # ask VAR "prompt" "default"
+  eval "_cur=\${$1:-}"; [ -n "${_cur:-}" ] && return 0
+  printf '%s [%s]: ' "$2" "${3:-}" >&2; read -r _ans || _ans=""
+  eval "$1=\"\${_ans:-$3}\""
+}
+OS="$(uname -s)"
+PROJECT_DIR="$(pwd)"
+[ -d "$PROJECT_DIR/.git" ] || warn "Note: $PROJECT_DIR is not a git repo root; the role will install here anyway."
+# --- Resolve the template source (local checkout wins, else GitHub) ----------
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd || echo "")"
+if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/copier.yml" ]; then
+  TEMPLATE_SRC="$SCRIPT_DIR"
+else
+  TEMPLATE_SRC="${HAT_TEMPLATE:-gh:delorenj/hermes-agent-template}"
+fi
+say "== Hermes local install =="
+say "   project:  $PROJECT_DIR"
+say "   template: $TEMPLATE_SRC"
+say "   os:       $OS"
+# --- 1. Ensure the hermes CLI ------------------------------------------------
+if command -v hermes >/dev/null 2>&1; then
+  say "1. hermes: found ($(command -v hermes))"
+else
+  say "1. hermes: not found — installing"
+  run "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash"
+  command -v hermes >/dev/null 2>&1 || die "hermes install did not put 'hermes' on PATH. Open a new shell and re-run."
+fi
+HERMES_BIN="$(command -v hermes)"
+# --- 2. Ensure copier --------------------------------------------------------
+if command -v copier >/dev/null 2>&1; then
+  say "2. copier: found"
+else
+  say "2. copier: not found — installing"
+  if command -v uv >/dev/null 2>&1; then run "uv tool install copier"
+  else run "python3 -m pip install --user copier"; fi
+  command -v copier >/dev/null 2>&1 || die "copier install failed. Install it (uv tool install copier) and re-run."
+fi
+# --- 3. Host-correct, local config.toml (so 01-config doesn't seed delo defaults)
+CFG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/hermes-agent-template"
+CFG="$CFG_DIR/config.toml"
+if [ -f "$CFG" ]; then
+  say "3. config: exists ($CFG) — leaving it"
+else
+  say "3. config: writing local defaults to $CFG"
+  if [ "${HAT_DRY_RUN:-0}" != "1" ]; then
+    mkdir -p "$CFG_DIR"
+    cat > "$CFG" <<TOML
+# Local install — cloud fields intentionally blank.
+[fleet]
+hermes_bin = "$HERMES_BIN"
+hermes_repo = "$HOME/.hermes/hermes-agent"
+fleet_env = "~/.hermes/fleet.env"
+registry_file = "~/.hermes/agents-registry.yaml"
+[github]
+runtime_repo_owner = ""
+[plane]
+base = "${PLANE_BASE:-}"
+workspace = ""
+[bloodbank]
+nats_host = "127.0.0.1"
+nats_port = 4222
+TOML
+  fi
+fi
+# --- 4. Provider credentials + board binding ---------------------------------
+ask HAT_PROVIDER "Ticket provider (linear|plane|trello)" "plane"
+PROVIDER="$HAT_PROVIDER"
+ask HAT_REPO "Project/repo name" "$(basename "$PROJECT_DIR" | tr '[:upper:]' '[:lower:]')"
+REPO="$HAT_REPO"
+SM_ENV="$HOME/.hermes/${REPO}-scrum-master.env"
+# These get written into the scrum-master role.yaml binding after render.
+# Pre-seed from optional env knobs so the install can run non-interactively.
+TP_WORKSPACE="${HAT_PLANE_WORKSPACE:-}"; TP_PROJECT="${HAT_PLANE_PROJECT:-}"
+TP_TEAM="${HAT_LINEAR_TEAM:-}"; TP_BOARD="${HAT_TRELLO_BOARD:-}"
+case "$PROVIDER" in
+  plane)
+    ask PLANE_BASE "Plane base URL" "https://app.plane.so"
+    : "${PLANE_API_KEY:?Set PLANE_API_KEY in your environment, then re-run}"
+    ask TP_WORKSPACE "Plane workspace slug" ""
+    [ -n "$TP_WORKSPACE" ] || die "workspace is required"
+    say "   Plane projects in '$TP_WORKSPACE':"
+    _pj="$(mktemp)"
+    curl -fsS "$PLANE_BASE/api/v1/workspaces/$TP_WORKSPACE/projects/?per_page=100" \
+      -H "X-API-Key: $PLANE_API_KEY" > "$_pj" 2>/dev/null || true
+    python3 - "$_pj" <<'PY' 2>/dev/null || warn "   (could not list projects; check PLANE_API_KEY/base/workspace)"
+import sys, json
+try:
+    d = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+rows = d.get("results", d if isinstance(d, list) else [])
+for p in rows:
+    print(f"     {p.get('id')}  {(p.get('identifier') or ''):8} {p.get('name')}")
+PY
+    rm -f "$_pj"
+    ask TP_PROJECT "Plane project UUID to manage" ""
+    [ -n "$TP_PROJECT" ] || die "project UUID is required"
+    CRED_LINES="PLANE_API_KEY=$PLANE_API_KEY
+PLANE_BASE=$PLANE_BASE"
+    ;;
+  linear)
+    : "${LINEAR_API_KEY:?Set LINEAR_API_KEY in your environment, then re-run}"
+    ask TP_TEAM "Linear team key (for example DEL)" ""
+    [ -n "$TP_TEAM" ] || die "team key is required"
+    CRED_LINES="LINEAR_API_KEY=$LINEAR_API_KEY"
+    ;;
+  trello)
+    : "${TRELLO_KEY:?Set TRELLO_KEY in your environment, then re-run}"
+    : "${TRELLO_TOKEN:?Set TRELLO_TOKEN in your environment, then re-run}"
+    ask TP_BOARD "Trello board id" ""
+    [ -n "$TP_BOARD" ] || die "board id is required"
+    CRED_LINES="TRELLO_KEY=$TRELLO_KEY
+TRELLO_TOKEN=$TRELLO_TOKEN"
+    ;;
+  *) die "unknown provider: $PROVIDER" ;;
+esac
+say "4. writing provider credentials to $SM_ENV"
+if [ "${HAT_DRY_RUN:-0}" != "1" ]; then
+  mkdir -p "$HOME/.hermes"; umask 077
+  printf '%s\n' "$CRED_LINES" > "$SM_ENV"
+fi
+# --- 5. Provision each role with copier (cloud + Telegram + systemd skipped) --
+# No provider key in copier's env, so 42-ticket-provider skips board creation;
+# we bind to the existing board below.
+export SKIP_TELEGRAM=1 SKIP_EMAIL=1 SKIP_RUNTIME_REPO=1 SKIP_PLANE=1 \
+       SKIP_BLOODBANK=1 SKIP_SYSTEMD=1
+ROLES="${HAT_ROLES:-pm scrum-master}"
+for ROLE in $ROLES; do
+  say "5. provisioning role: $ROLE"
+  DEST="$PROJECT_DIR/agents/hermes/$ROLE"
+  # Scrub provider creds from copier's environment so 42-ticket-provider skips
+  # board CREATION; we bind to the existing board in step 6 instead.
+  run "env -u PLANE_API_KEY -u PLANE_33GOD_API_KEY -u LINEAR_API_KEY \
+        -u TRELLO_KEY -u TRELLO_TOKEN \
+        copier copy '$TEMPLATE_SRC' '$DEST' --trust --defaults --overwrite \
+        --data target_repo='$REPO' --data role='$ROLE' --data ticket_provider='$PROVIDER'"
+done
+# --- 6. Bind the Scrum Master to the existing board --------------------------
+SM_ROLE="$PROJECT_DIR/agents/hermes/scrum-master/role.yaml"
+if [ -f "$SM_ROLE" ] && [ "${HAT_DRY_RUN:-0}" != "1" ]; then
+  say "6. binding scrum-master to your $PROVIDER board"
+  TP_WORKSPACE="$TP_WORKSPACE" TP_PROJECT="$TP_PROJECT" TP_TEAM="$TP_TEAM" \
+  TP_BOARD="$TP_BOARD" PROVIDER="$PROVIDER" python3 - "$SM_ROLE" <<'PY'
+import os, re, sys, pathlib
+p = pathlib.Path(sys.argv[1]); t = p.read_text()
+def setleaf(text, key, val):
+    if not val: return text
+    new, n = re.subn(rf'(?m)^(\s*{re.escape(key)}:\s*)"?[^"\n]*"?\s*$', rf'\g<1>"{val}"', text, count=1)
+    return new if n else text
+t = setleaf(t, "workspace", os.environ.get("TP_WORKSPACE",""))
+t = setleaf(t, "project",   os.environ.get("TP_PROJECT",""))
+t = setleaf(t, "team",      os.environ.get("TP_TEAM",""))
+t = setleaf(t, "board",     os.environ.get("TP_BOARD",""))
+p.write_text(t)
+print("   bound:", {k:v for k,v in os.environ.items() if k.startswith("TP_") and v})
+PY
+fi
+# --- 7. Smoke test the board connection --------------------------------------
+if [ "${HAT_DRY_RUN:-0}" != "1" ] && [ -f "$SM_ROLE" ]; then
+  say "7. smoke test: reading your board through the adapter"
+  LIB="$PROJECT_DIR/agents/hermes/scrum-master/.scripts/lib/ticket-provider.sh"
+  ( set -a; . "$SM_ENV" 2>/dev/null; set +a
+    bash -c '. "$1"; tp resolve && echo "   issues: $(tp list_issues | python3 -c "import sys,json;print(len(json.load(sys.stdin)))")"' _ "$LIB" ) \
+    || warn "   smoke test failed — check the binding in $SM_ROLE and creds in $SM_ENV"
+fi
+say ""
+say "Done. Talk to the PM:   agents/hermes/pm/hermes chat \"status\""
+if [ "$OS" = "Darwin" ]; then
+  say "Sentinel (launchd):     launchctl list | grep $REPO-scrum-master"
+else
+  say "Sentinel (systemd):     systemctl --user status hermes-$REPO-scrum-master-continuous-ticket-sentinel.timer"
+fi
+say "Provider creds live in: $SM_ENV"

package/templates/hermes-agent/runtime-scaffold/.gitattributes ADDED Viewed

@@ -0,0 +1,10 @@
+# Route binary state through git-lfs so the checkpoint repo doesn't bloat.
+*.db          filter=lfs diff=lfs merge=lfs -text
+*.sqlite      filter=lfs diff=lfs merge=lfs -text
+*.sqlite3     filter=lfs diff=lfs merge=lfs -text
+*.png         filter=lfs diff=lfs merge=lfs -text
+*.jpg         filter=lfs diff=lfs merge=lfs -text
+*.jpeg        filter=lfs diff=lfs merge=lfs -text
+*.wav         filter=lfs diff=lfs merge=lfs -text
+*.mp3         filter=lfs diff=lfs merge=lfs -text
+*.mp4         filter=lfs diff=lfs merge=lfs -text

package/templates/hermes-agent/runtime-scaffold/README.md ADDED Viewed

@@ -0,0 +1,52 @@
+# {{agent_id}} — runtime
+This is the durable runtime for the **{{display_name}}** agent. The named
+Hermes profile `{{profile_name}}` points here from `~/.hermes/profiles/{{profile_name}}`,
+so Hermes sees an ordinary profile while this repo stays git-tracked and
+recoverable across machines.
+## What's in here
+| Path | Tracked? | Purpose |
+| --- | --- | --- |
+| `profile.yaml` | yes | Opts this profile into inheriting config from default |
+| `config.yaml` | yes | Local config overrides only; shared defaults come from the fleet default |
+| `SOUL.md` | yes | The agent's personality, evolves over time |
+| `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
+| `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
+| `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
+| `bloodbank-consumer.py` | yes | NATS subscriber for repo-scoped events |
+| `decisions/` | yes | Agent-emitted decisions, one file per important call |
+| `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
+| `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |
+| `audio_cache/`, `image_cache/` | **no** | Regenerable caches |
+| `sandboxes/` | **no** | Per-session ephemeral execution dirs |
+| `bloodbank-inbox/` | **no** | Inbox queue for incoming bloodbank events |
+## Checkpoint cadence
+- Hourly: systemd `--user` timer `hermes-{{agent_id}}-checkpoint.timer`
+- On session end: hermes Stop hook (TODO: hook script in `~/.hermes/hooks/`)
+The checkpoint script lives in the parent's `.scripts/checkpoint.sh`. It
+`git add -A`, commits only if dirty, and pushes to `origin`.
+## Restoring on a new machine
+```bash
+cd /path/to/parent-project
+git submodule update --init --recursive
+git -C agents/hermes/{{role}}/runtime lfs pull
+# Provide the per-runtime secrets the submodule deliberately excluded:
+cp ~/path/to/your/.env       agents/hermes/{{role}}/runtime/.env
+# OAuth provider credentials are shared across the fleet. If needed, login once:
+agents/hermes/{{role}}/hermes auth add openai-codex
+agents/hermes/{{role}}/hermes status
+```
+## DO NOT manually edit on multiple machines
+This repo is a single-writer system. Either run the agent on machine A or
+machine B — not both. The checkpoint commit will fast-forward; concurrent
+edits cause merge pain. If you really need to fork the agent (e.g. for
+experimentation), branch this repo.

package/templates/hermes-agent/runtime-scaffold/bloodbank-consumer.py ADDED Viewed

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Bloodbank consumer for hermes agent {{agent_id}}.
+Subscribes to:
+    bloodbank.evt.v1.repo.{{repo}}.>
+    bloodbank.cmd.v1.agent.{{agent_id}}.>
+For each event/command received, writes it to the agent's notification queue at
+$HERMES_HOME/bloodbank-inbox/<timestamp>.json so the gateway can ingest it on
+the next tick. Reconnects on broker churn; idempotent across restarts.
+Generated by hermes-agent-template/runtime-scaffold/bloodbank-consumer.py and
+rendered with role-specific values at provision time. Re-render by re-running
+agents/hermes/{{role}}/.scripts/20-runtime-repo.sh — do NOT edit by hand.
+"""
+import asyncio
+import json
+import os
+import pathlib
+import signal
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+try:
+    import nats
+except ImportError:
+    sys.stderr.write("nats-py not installed. install with: pip install nats-py\n")
+    sys.exit(2)
+HERMES_HOME = pathlib.Path(os.environ.get("HERMES_HOME", str(pathlib.Path.home() / ".hermes")))
+INBOX_DIR = HERMES_HOME / "bloodbank-inbox"
+INBOX_DIR.mkdir(parents=True, exist_ok=True)
+NATS_HOST = os.environ.get("BLOODBANK_NATS_HOST", "127.0.0.1")
+NATS_PORT = int(os.environ.get("BLOODBANK_NATS_PORT", "4222"))
+NATS_URL = f"nats://{NATS_HOST}:{NATS_PORT}"
+AGENT_ID = "{{agent_id}}"
+REPO     = "{{repo}}"
+ROLE     = "{{role}}"
+PRODUCER = f"hermes-agent:{AGENT_ID}"
+SOURCE   = f"hermes://agent/{AGENT_ID}"
+SUBJECTS = [
+    f"bloodbank.evt.v1.repo.{REPO}.>",
+    f"bloodbank.cmd.v1.agent.{AGENT_ID}.>",
+]
+KIND_MARKERS = {"event": "evt", "command": "cmd", "reply": "rpy"}
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+def _subject_and_domain(ce_type, kind):
+    parts = ce_type.split(".")
+    if len(parts) != 5 or parts[0] != "bloodbank" or not parts[1].startswith("v"):
+        raise ValueError(f"type {ce_type!r} must match bloodbank.vN.<domain>.<entity>.<action>")
+    if kind not in KIND_MARKERS:
+        raise ValueError(f"unknown envelope kind {kind!r}")
+    _vendor, version, domain, entity, action = parts
+    return f"bloodbank.{KIND_MARKERS[kind]}.{version}.{domain}.{entity}.{action}", domain
+def build_envelope(ce_type, data, *, kind="event", correlationid=None, causationid=None):
+    """Mirror of bloodbank/services/agent-hooks/core/envelope.build_envelope."""
+    subject, domain = _subject_and_domain(ce_type, kind)
+    env = {
+        "specversion": "1.0",
+        "type": ce_type,
+        "id": str(uuid.uuid4()),
+        "source": SOURCE,
+        "subject": subject,
+        "time": _now(),
+        "datacontenttype": "application/json",
+        "kind": kind,
+        "producer": PRODUCER,
+        "service": "hermes-agent",
+        "domain": domain,
+        "actor": {"type": "agent", "agent_id": AGENT_ID, "cli": "hermes"},
+        "data": data,
+        "correlationid": correlationid or str(uuid.uuid4()),
+        "causationid": causationid or str(uuid.uuid4()),
+    }
+    if kind == "event":
+        env["ordering_key"] = f"agent:{AGENT_ID}"
+    return env
+async def main():
+    nc = await nats.connect(NATS_URL, name=f"hermes-{AGENT_ID}")
+    stop = asyncio.Event()
+    async def on_msg(msg):
+        try:
+            payload = json.loads(msg.data.decode())
+        except Exception:
+            payload = {"_raw": msg.data.decode(errors="replace")}
+        entry = {
+            "received_at": _now(),
+            "subject": msg.subject,
+            "reply_to": msg.reply,
+            "payload": payload,
+        }
+        fname = f"{int(time.time()*1000):013d}-{uuid.uuid4().hex[:8]}.json"
+        tmp = INBOX_DIR / (fname + ".tmp")
+        tmp.write_text(json.dumps(entry, indent=2))
+        tmp.rename(INBOX_DIR / fname)
+        sys.stderr.write(f"[bloodbank-consumer:{AGENT_ID}] {msg.subject} -> {fname}\n")
+    for subj in SUBJECTS:
+        await nc.subscribe(subj, cb=on_msg)
+        sys.stderr.write(f"[bloodbank-consumer:{AGENT_ID}] subscribed: {subj}\n")
+    # Announce presence
+    online = build_envelope(
+        "bloodbank.v1.agent.online.changed",
+        {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "online"},
+    )
+    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(online).encode())
+    def _shutdown(*_):
+        stop.set()
+    signal.signal(signal.SIGTERM, _shutdown)
+    signal.signal(signal.SIGINT, _shutdown)
+    await stop.wait()
+    offline = build_envelope(
+        "bloodbank.v1.agent.online.changed",
+        {"agent_id": AGENT_ID, "repo": REPO, "role": ROLE, "state": "offline"},
+    )
+    await nc.publish("bloodbank.evt.v1.agent.online.changed", json.dumps(offline).encode())
+    await nc.drain()
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

package/templates/hermes-agent/runtime-scaffold/decisions/.gitkeep ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ # Agents drop one markdown file per important decision here.
2	+ # Filename convention: YYYY-MM-DD-HHMMSS-<slug>.md

package/templates/hermes-agent/runtime-scaffold/logs/.gitkeep ADDED Viewed

	@@ -0,0 +1 @@
1	+ # keep logs/ in the repo so per-agent log paths exist on first checkout