From 611a474b16b2151096726169b75e4fcc9fe98ca7 Mon Sep 17 00:00:00 2001 From: Ty Date: Sun, 27 Sep 2026 17:33:37 +0000 Subject: [PATCH] Add companion manual: webhooks + Regis integration (draft v0.1) --- WEBHOOKS-AND-REGIS.md | 210 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 WEBHOOKS-AND-REGIS.md diff --git a/WEBHOOKS-AND-REGIS.md b/WEBHOOKS-AND-REGIS.md new file mode 100644 index 0000000..a7d3bb7 --- /dev/null +++ b/WEBHOOKS-AND-REGIS.md @@ -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:///api/v1/repos///contents/" \ + -H "Authorization: token " \ + -H "Content-Type: application/json" \ + -d '{"branch":"main","message":"mailbox: -> ","content":"","sha":""}' +``` + +## 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 "" \ + -H "Authorization: " \ + -H "Content-Type: text/plain" \ + --max-time 10 \ + --data "new entry 14:05 PT, " +``` + +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.