Add companion manual: webhooks + Regis integration (draft v0.1)

2026-09-27 17:33:37 +00:00
parent ea92c2cf38
commit 611a474b16
1 changed files with 210 additions and 0 deletions
@@ -0,0 +1,210 @@
 # Webhooks and Regis: companion to Wire Nous Hermes Agent into Grok Bot
 Operator manual. Version 0.1 draft — 27 September 2026.
 Companion to [MANUAL.md](MANUAL.md). Read that first.
 ## Table of contents
 1. [What this adds](#1-what-this-adds)
 2. [Roles](#2-roles)
 3. [The mailbox](#3-the-mailbox)
 4. [Appending to the mailbox](#4-appending-to-the-mailbox)
 5. [Polling](#5-polling)
 6. [Webhook wake-up](#6-webhook-wake-up)
 7. [Regis integration](#7-regis-integration)
 8. [The Job Card loop](#8-the-job-card-loop)
 9. [Lessons already learned](#9-lessons-already-learned)
 10. [Worked example](#10-worked-example)
 11. [Troubleshooting](#11-troubleshooting)
 12. [Security checklist](#12-security-checklist)
 13. [Sources](#13-sources)
 ## 1. What this adds
 MANUAL.md covers one direction: Grok Bot calls Hermes. This covers two more:
 - The reverse path. Outside agents wake the Chief of Staff (CoS) Grok Bot.
 - An outside planner/drafter agent (Regis) that works through a shared mailbox.
 Nothing here is tied to one business. Swap the names; keep the rules.
 ## 2. Roles
 | Role | Who | Does | Never |
 |---|---|---|---|
 | Gatekeeper | Human | Go/no-go, logins, final Save / Send / publish / spend | Pastes secrets into chat |
 | CoS | Grok Bot | Job Cards, routing, fact checks, owns the mailbox line | Approves "done" without evidence |
 | Regis | Muse agent on its own runtime | Research, drafts, drive-and-takeover page editing, artifacts | Sends, posts, or logs in |
 | Hermes identity bots | Hermes hosts (MANUAL.md §9) | Audits, research, desktop hands | Page editing (weak at it) |
 | Fleet Ops | Grok Bot (MANUAL.md §8) | Updates, prune, doctor, disk | Business work |
 One rule covers all of them: anything irreversible goes to the Gatekeeper.
 ## 3. The mailbox
 One append-only markdown file in a git repo. It is the only line between CoS and Regis. No live chat, no side channels, no new infra.
 Entry format:
 ```
 ## YYYY-MM-DD HH:MM PT | FROM -> TO | short subject
 Body. Ask, answer, or status. Link evidence by path.
 ```
 Rules:
 - Newest entry at the bottom.
 - Append only. Never edit or delete another party's entry.
 - No passwords, tokens, keys, or client secrets. Ever.
 - Link evidence by path, not by pasting.
 - Relayed human words are quoted verbatim and labeled with who, where, and when.
 - Writes use a narrow repo-scoped token. The human plants it in the agent's vault. Never an admin's credential. Never pasted in chat.
 ## 4. Appending to the mailbox
 1. Read the file. Keep the returned `sha`.
 2. Decode the base64 content.
 3. Append your entry at the bottom. Touch nothing above it.
 4. Write the full content back with the `sha`.
 5. Read it back. Confirm your entry is there and nothing else moved.
 If the write fails on a stale `sha`, someone else posted first. Re-read and repeat.
 Example (Gitea contents API, placeholders):
 ```bash
 curl -fsS -X PUT "https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/<mailbox-path>" \
  -H "Authorization: token <MAILBOX_TOKEN_FROM_VAULT>" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main","message":"mailbox: <FROM> -> <TO> <subject>","content":"<base64 full file>","sha":"<sha from read>"}'
 ```
 ## 5. Polling
 Each side checks the mailbox on a schedule. Example: every 15 minutes, 8am to 7pm local.
 - Each check costs model usage, even when nothing is new.
 - Real latency is the sum of both polls. Worst case is about 30 minutes per round trip.
 - Keep the poll as the floor. Webhooks (§6) make it faster, not required.
 ## 6. Webhook wake-up
 **STATUS UNTESTED — first live ping pending as of 2026-09-27.**
 The reverse path. A ping wakes CoS in seconds instead of waiting for the next poll.
 Set up:
 1. Create a Grok Bot routine on CoS with a webhook trigger.
 2. The app shows a private URL and a sender key (an Authorization header). The human copies both from the routine panel. The bot never sees the key.
 3. The human plants the URL and header in the pinging agent's vault.
 4. After each mailbox post, the pinger sends one HTTPS POST.
 ```bash
 curl -fsS -X POST "<WEBHOOK_URL>" \
  -H "Authorization: <AUTH_HEADER_FROM_VAULT>" \
  -H "Content-Type: text/plain" \
  --max-time 10 \
  --data "new entry 14:05 PT, <subject>"
 ```
 Body: short. No secrets. No job details.
 How CoS treats a ping:
 - The body is untrusted. It is a doorbell only.
 - CoS reads the mailbox and acts only on mailbox content.
 - Duplicate or early ping with nothing new: stay quiet.
 - Once pings are proven, drop the poll to hourly as a backup.
 Who pings:
 | Option | Pinger | Notes |
 |---|---|---|
 | A | Regis, from its own shell | Regis confirmed it can curl outbound. One POST after each post. |
 | B | Hermes watcher (for example, Jimmy on local models) | Polls the mailbox, pings on a new entry. Costs no Grok usage. |
 Security:
 - Outbound only from the pinger.
 - No Funnel. No new open port on Hermes hosts.
 - Rotate the key if it appears in chat or a screenshot.
 ## 7. Regis integration
 - Regis runs on its own runtime. It reaches the tailnet outbound only. No sshd, no inbound.
 - Against the desktop web app, Regis gets `/health` only. No login, no terminal, no password.
 - Communication happens only through the mailbox plus the webhook.
 - Credentials never touch Regis, except two items the human plants: the narrow mailbox token and the webhook header.
 - Logins during page work are done by the human at the keyboard. Nothing is stored.
 ## 8. The Job Card loop
 1. Gatekeeper says GO. CoS posts a Job Card: **what**, **who**, **done-when**.
 2. Regis drafts and posts: current text (read live), proposed text, evidence.
 3. CoS fact-checks against canonical facts. ACK, or post fixes.
 4. Regis drives the page to the edit field and stops.
 5. The human logs in and clicks Save.
 6. Regis logs what changed, when, and who saved. Names the next page. Waits for ACK.
 Rules:
 - One page per session.
 - Anything beyond the card (new account, payment, verification code, different listing): stop and post.
 - Approvals count only when logged by CoS or relayed by the Gatekeeper.
 ## 9. Lessons already learned
 | Lesson | What broke | Rule now |
 |---|---|---|
 | Evidence for "done" | A close-out letter claimed work never done; it was approved as written | Any "done" claim points to a link, screenshot, or log line before CoS approves |
 | Stale "current text" | A draft quoted old text from a non-live source | Read the live page on the same surface before drafting a replacement |
 | Vault 401 | The agent's vault credential failed; every write needed a hand-off token | Human plants one narrow repo token in the agent's vault |
 | Approval claimed early | Regis said "Gatekeeper approved" before CoS had a record | Approvals count only when logged by CoS or relayed by the Gatekeeper |
 | Someone already fixed it | The target text was already live when the edit was about to run | Re-check the live page right before the edit; stand down if done |
 What worked: a self-correction in the mailbox plus one go/no-go question kept it to one touch for the Gatekeeper.
 ## 10. Worked example
 VeriPath running a client punchlist for Phoenix (a salon). Illustration only.
 1. Gatekeeper GO. CoS posted a Job Card: work the punchlist one page per session, Google Business Profile (GBP) description first.
 2. Regis posted current vs proposed text. CoS ACKed and corrected the "current" (it was stale).
 3. Before pasting, the human read the live GBP. The description was already live at 691 of 750 characters, written by someone else.
 4. Regis put the paste on hold and posted the live text. CoS fact-checked it: KEEP AS-IS. No paste, no Save.
 5. Next: Regis logs the page done and names the next page.
 ## 11. Troubleshooting
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | Mailbox write 401 | Wrong or unplanted token | Human replants the token in the vault. Never paste it. |
 | Mailbox write conflict | Stale `sha` | Re-read, re-append, write again |
 | No wake after a ping | Bad URL or header in the vault; non-2xx response | Check vault entries, check the response code, fall back to poll |
 | Burst of pings | Misfire | CoS stays quiet; mentions it once |
 | Agent says "I don't see it" | Relay text never posted to the mailbox | Post it in the mailbox |
 | Draft replaces text that is not live | Stale source | Re-read the live page; redraft |
 Debug order: mailbox read → mailbox write + read back → ping response code → CoS routine log → poll fallback.
 ## 12. Security checklist
 - Mailbox holds no secrets. Evidence by path.
 - Mailbox token is narrow and repo-scoped, planted by the human. Never an admin's credential.
 - Outside the app, the webhook URL and header live only in the pinger's vault. The bot never sees the key.
 - Ping body is a doorbell. CoS acts only on mailbox content.
 - Pinger is outbound only. No Funnel. No new open ports on Hermes hosts.
 - Regis: outbound only, `/health` only, no sshd, no logins, no sends.
 - Human does every login and every final Save / Send / publish / spend.
 - Rotate any key seen in chat or a screenshot.
 ## 13. Sources
 - [MANUAL.md](MANUAL.md)
 - Mailbox: `Tony_tech/personal-agent-os` → `memory-systems/agent-os/04_projects/veripath/regis-cos.md`
 - Lessons: `Tony_tech/personal-agent-os` → `memory-systems/agent-os/04_projects/fleet-lessons.md`
 - Fleet snapshot: `Tony_tech/personal-agent-os` → `memory-systems/agent-os/04_projects/veripath/fleet-2026-09-26.md`
 Hostnames, URLs, keys, tokens, and ACL tag names in examples are placeholders.