From abfad9b2bddbb24cf30333c60f7f196eff501343 Mon Sep 17 00:00:00 2001 From: Ty Date: Sun, 27 Sep 2026 17:36:35 +0000 Subject: [PATCH] Remove companion draft; merged into FLEET-MANUAL.md --- WEBHOOKS-AND-REGIS.md | 210 ------------------------------------------ 1 file changed, 210 deletions(-) delete mode 100644 WEBHOOKS-AND-REGIS.md diff --git a/WEBHOOKS-AND-REGIS.md b/WEBHOOKS-AND-REGIS.md deleted file mode 100644 index a7d3bb7..0000000 --- a/WEBHOOKS-AND-REGIS.md +++ /dev/null @@ -1,210 +0,0 @@ -# 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.