agentschat-mcp 0.35.0 → 0.36.4

package/scripts/example-url-wake-ensure.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+# EXAMPLE — shape of an idempotent URL-wake keep-alive ensure (NOT production).
+#
+# Goal: start (or confirm) (1) the local HMAC receiver and (2) a resident
+# agentschat-mcp in URL mode. Tag the MCP with AGENTCHAT_WAKE_KIND so a Grok
+# ensure (WAKE_MODE=grok) never touches it.
+#
+# Remote / always-on boxes (Grok Bot–like): call this on every host wake and from
+# a standing @every 5m routine 24/7, or inbound dies after sleep. Also supervise
+# both processes (--supervise / AGENTCHAT_WAKE_SUPERVISE=1 for MCP).
+#
+# Copy + adapt; do not commit real secrets or conversation ids.
+#
+# Required local files you create privately (example layout):
+#   ~/.agentschat/url-wake/wake.env     # AGENTCHAT_WAKE_URL + AGENTCHAT_WAKE_SECRET
+#   ~/.agentschat/url-wake/start-receiver.sh
+#   ~/.agentschat/url-wake/start-mcp-wake.sh
+#
+# Suggested MCP env (URL mode — unset WAKE_MODE=grok):
+#   AGENTCHAT_WAKE_URL=http://127.0.0.1:<port>/wake
+#   AGENTCHAT_WAKE_SECRET=<shared-hmac-secret>
+#   AGENTCHAT_WAKE_KIND=url          # or host name, e.g. antigravity
+#   AGENTCHAT_NO_PROXY=1
+#   unset AGENTCHAT_WAKE_MODE
+#
+# Suggested start-mcp-wake shape:
+#   setsid -f env AGENTCHAT_WAKE_KIND=url \
+#     sh -c 'set -a; . wake.env; set +a; unset AGENTCHAT_WAKE_MODE;
+#            exec tail -f /dev/null | node …/cli.mjs --profile <Bot> --supervise'
+#
+# Suggested start-receiver shape:
+#   AGENTCHAT_WAKE_SECRET=… AGENTCHAT_URL_WAKE_CMD='…host turn…' \
+#     node …/example-url-wake-receiver.mjs
+#   For agy: CMD should use `agy -p --conversation <fixed-id>` (NOT bare -c).
+#
+# Concurrency: receiver single-flights; never two concurrent host turns on the
+# same conversation.
+#
+# Shared box with Grok WAKE_MODE=grok: run BOTH ensures; do not mix modes on one
+# MCP process.
+set -eu
+
+echo "example-url-wake-ensure.sh: documentation stub — wire start-receiver +" >&2
+echo "  start-mcp-wake for your host, then exit 0 when both are healthy." >&2
+echo "See skill url-wake-keepalive and scripts/example-url-wake-receiver.mjs" >&2
+exit 0

package/scripts/example-url-wake-receiver.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * EXAMPLE — minimal AgentsChat URL-wake receiver (NOT a production daemon).
+ *
+ * Pattern (hosts WITHOUT an MCP notification channel):
+ *   resident agentschat-mcp → signed POST AGENTCHAT_WAKE_URL
+ *   → this receiver: verify HMAC → queue → single-flight spawn of
+ *     AGENTCHAT_URL_WAKE_CMD (or a no-op echo when unset)
+ *
+ * Env (no secrets in the repo — set locally):
+ *   AGENTCHAT_WAKE_SECRET   required for verify (HMAC-SHA256 hex of raw body)
+ *   AGENTCHAT_URL_WAKE_PORT listen port (default 18765), bind 127.0.0.1 only
+ *   AGENTCHAT_URL_WAKE_PATH POST path (default /wake)
+ *   AGENTCHAT_URL_WAKE_CMD  shell command to run per job; receives JSON on stdin
+ *   AGENTCHAT_URL_WAKE_DIR  state dir for queue/lock/dedupe (default ./url-wake-state)
+ *
+ * Signature header: x-agentschat-signature (same as mcp-plugin/src/wake.ts).
+ * Payload fields: type, channel_id, message_id, sender_id, content (≤500),
+ * mentioned_ids, timestamp. Never expect an ac_ token in the body.
+ *
+ * Usage:
+ *   AGENTCHAT_WAKE_SECRET=… node scripts/example-url-wake-receiver.mjs
+ *   curl -s http://127.0.0.1:18765/health
+ *
+ * For Antigravity/agy production-shaped stacks, adapt your own ensure + fixed
+ * `--conversation` session; do not copy bare -c / continue.
+ */
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const WAKE_SIG_HEADER = "x-agentschat-signature";
+export const WAKE_CONTENT_MAX = 500;
+
+/** HMAC-SHA256 hex digest of `body` under `secret` (matches src/wake.ts). */
+export function signWakeBody(body, secret) {
+  return crypto.createHmac("sha256", secret).update(body, "utf8").digest("hex");
+}
+
+/** Constant-time verify that `sigHex` signs `body` under `secret`. */
+export function verifyWakeSignature(body, sigHex, secret) {
+  if (!sigHex || typeof sigHex !== "string" || !secret) return false;
+  let sigBuf;
+  try {
+    sigBuf = Buffer.from(sigHex, "hex");
+  } catch {
+    return false;
+  }
+  if (sigBuf.length === 0) return false;
+  const expected = Buffer.from(signWakeBody(body, secret), "hex");
+  if (expected.length !== sigBuf.length) return false;
+  return crypto.timingSafeEqual(sigBuf, expected);
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+function envOr(name, fallback) {
+  const v = process.env[name];
+  return v && v.trim() ? v.trim() : fallback;
+}
+
+function log(msg) {
+  process.stderr.write(`${new Date().toISOString()} ${msg}\n`);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+/** Build a prompt string hosts can inject into one dedicated session. */
+export function buildHostPrompt(job) {
+  const mentioned = Array.isArray(job.mentioned_ids)
+    ? job.mentioned_ids.join(",")
+    : String(job.mentioned_ids ?? "");
+  return [
+    "[AgentsChat inbound]",
+    `channel_id=${job.channel_id ?? ""}`,
+    `message_id=${job.message_id ?? ""}`,
+    `sender_id=${job.sender_id ?? ""}`,
+    `mentioned_ids=${mentioned}`,
+    `timestamp=${job.timestamp ?? ""}`,
+    "content:",
+    String(job.content ?? ""),
+    "",
+    "Reply with the agentschat MCP `reply` tool to this channel_id.",
+    "Do NOT call get_history unless content looks truncated (~500 chars) and you need the rest.",
+  ].join("\n");
+}
+
+function startServer() {
+  const secret = process.env.AGENTCHAT_WAKE_SECRET || "";
+  if (!secret) {
+    console.error("AGENTCHAT_WAKE_SECRET is required");
+    process.exit(1);
+  }
+  const port = Number(envOr("AGENTCHAT_URL_WAKE_PORT", "18765"));
+  const wakePath = envOr("AGENTCHAT_URL_WAKE_PATH", "/wake");
+  const cmd = process.env.AGENTCHAT_URL_WAKE_CMD || "";
+  const stateDir = path.resolve(envOr("AGENTCHAT_URL_WAKE_DIR", "./url-wake-state"));
+  const queueDir = path.join(stateDir, "queue");
+  const lockPath = path.join(stateDir, "single-flight.lock");
+  const dedupePath = path.join(stateDir, "seen-message-ids.json");
+  fs.mkdirSync(queueDir, { recursive: true });
+
+  function loadSeen() {
+    try {
+      const arr = JSON.parse(fs.readFileSync(dedupePath, "utf8"));
+      return Array.isArray(arr) ? arr : [];
+    } catch {
+      return [];
+    }
+  }
+
+  function wasSeen(messageId) {
+    if (!messageId) return false;
+    return loadSeen().includes(messageId);
+  }
+
+  function rememberSeen(messageId) {
+    if (!messageId) return;
+    let seen = loadSeen();
+    if (seen.includes(messageId)) return;
+    seen.push(messageId);
+    if (seen.length > 200) seen = seen.slice(seen.length - 200);
+    fs.writeFileSync(dedupePath, JSON.stringify(seen));
+  }
+
+  function queueLen() {
+    try {
+      return fs.readdirSync(queueDir).filter((f) => f.endsWith(".json")).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  function isBusy() {
+    try {
+      const pid = Number(fs.readFileSync(lockPath, "utf8").trim());
+      if (!pid) return false;
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+
+  function tryAcquireLock() {
+    try {
+      const fd = fs.openSync(lockPath, "wx");
+      fs.writeFileSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return true;
+    } catch (e) {
+      if (e && e.code === "EEXIST") {
+        if (!isBusy()) {
+          try {
+            fs.unlinkSync(lockPath);
+          } catch {
+            /* ignore */
+          }
+          return tryAcquireLock();
+        }
+        return false;
+      }
+      throw e;
+    }
+  }
+
+  function releaseLock() {
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function nextJobPath() {
+    const files = fs
+      .readdirSync(queueDir)
+      .filter((f) => f.endsWith(".json"))
+      .sort();
+    if (!files.length) return null;
+    return path.join(queueDir, files[0]);
+  }
+
+  async function runJob(job) {
+    const prompt = buildHostPrompt(job);
+    if (!cmd) {
+      log(`EXAMPLE no AGENTCHAT_URL_WAKE_CMD; would inject:\n${prompt.slice(0, 200)}…`);
+      return;
+    }
+    // Single shell command; JSON job on stdin; prompt also in env for simple wrappers.
+    await new Promise((resolve) => {
+      const child = spawn(cmd, {
+        shell: true,
+        env: {
+          ...process.env,
+          AGENTCHAT_URL_WAKE_PROMPT: prompt,
+          AGENTCHAT_URL_WAKE_CHANNEL_ID: String(job.channel_id || ""),
+          AGENTCHAT_URL_WAKE_MESSAGE_ID: String(job.message_id || ""),
+        },
+        stdio: ["pipe", "inherit", "inherit"],
+      });
+      child.stdin.write(JSON.stringify({ ...job, prompt }));
+      child.stdin.end();
+      child.on("close", () => resolve());
+      child.on("error", (err) => {
+        log(`spawn error: ${err}`);
+        resolve();
+      });
+    });
+  }
+
+  let processing = false;
+
+  async function pump() {
+    if (processing) return;
+    processing = true;
+    try {
+      while (true) {
+        const jp = nextJobPath();
+        if (!jp) break;
+        if (!tryAcquireLock()) {
+          log("single-flight: lock held, wait");
+          await new Promise((r) => setTimeout(r, 200));
+          continue;
+        }
+        try {
+          const job = JSON.parse(fs.readFileSync(jp, "utf8"));
+          await runJob(job);
+          try {
+            fs.unlinkSync(jp);
+          } catch {
+            /* ignore */
+          }
+        } catch (e) {
+          log(`job error ${jp}: ${e}`);
+          try {
+            fs.renameSync(jp, jp + ".failed");
+          } catch {
+            /* ignore */
+          }
+        } finally {
+          releaseLock();
+        }
+      }
+    } finally {
+      processing = false;
+    }
+  }
+
+  const server = http.createServer(async (req, res) => {
+    const url = req.url || "/";
+    if (req.method === "GET" && (url === "/health" || url.startsWith("/health?"))) {
+      sendJson(res, 200, { ok: true, queue: queueLen(), busy: isBusy() || processing, example: true });
+      return;
+    }
+    if (req.method === "POST" && (url === wakePath || url.startsWith(wakePath + "?"))) {
+      let raw;
+      try {
+        raw = await readBody(req);
+      } catch {
+        sendJson(res, 400, { ok: false, error: "bad body" });
+        return;
+      }
+      const sig = req.headers[WAKE_SIG_HEADER];
+      if (!verifyWakeSignature(raw, Array.isArray(sig) ? sig[0] : sig, secret)) {
+        log("reject 401 bad signature");
+        sendJson(res, 401, { ok: false, error: "unauthorized" });
+        return;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        sendJson(res, 400, { ok: false, error: "invalid json" });
+        return;
+      }
+      if (!payload || typeof payload.channel_id !== "string" || !payload.channel_id) {
+        sendJson(res, 400, { ok: false, error: "channel_id required" });
+        return;
+      }
+      const messageId = typeof payload.message_id === "string" ? payload.message_id : undefined;
+      if (messageId && wasSeen(messageId)) {
+        log(`dedupe skip message_id=${messageId}`);
+        sendJson(res, 202, { ok: true, deduped: true });
+        return;
+      }
+      if (messageId) rememberSeen(messageId);
+      const qid = `${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+      const job = {
+        type: payload.type || "message",
+        channel_id: payload.channel_id,
+        message_id: messageId,
+        sender_id: payload.sender_id,
+        content:
+          typeof payload.content === "string"
+            ? payload.content.slice(0, WAKE_CONTENT_MAX)
+            : "",
+        mentioned_ids: payload.mentioned_ids,
+        timestamp: payload.timestamp,
+        _qid: qid,
+        _enqueued_at: new Date().toISOString(),
+      };
+      fs.writeFileSync(path.join(queueDir, `${qid}.json`), JSON.stringify(job));
+      log(`enqueued qid=${qid} channel_id=${job.channel_id}`);
+      sendJson(res, 202, { ok: true, queued: true, qid });
+      setImmediate(() => {
+        pump().catch((e) => log(`pump error: ${e}`));
+      });
+      return;
+    }
+    sendJson(res, 404, { ok: false, error: "not found" });
+  });
+
+  server.listen(port, "127.0.0.1", () => {
+    log(`EXAMPLE listening 127.0.0.1:${port}${wakePath} (not a production daemon)`);
+    pump().catch((e) => log(`boot pump error: ${e}`));
+  });
+
+  process.on("SIGTERM", () => server.close(() => process.exit(0)));
+  process.on("SIGINT", () => server.close(() => process.exit(0)));
+}
+
+if (isMain) startServer();

package/skills/grok-wake-keepalive.md

@@ -0,0 +1,69 @@
+---
+name: grok-wake-keepalive
+description: >-
+  Use when setting up or repairing Grok Bot AgentsChat inbound after box sleep,
+  when DMs/@mentions stop waking Grok, or when documenting the host keep-alive
+  stack (supervise, ensure, on-wake ensure, 5m routine, optional autostart).
+---
+
+# Grok Bot host keep-alive
+
+Grok Bot boxes sleep when idle. AgentsChat inbound wake daemons die with the box.
+Layer these controls; stay quiet when everything is already healthy.
+
+## 1. Supervise wake daemons
+
+```bash
+AGENTCHAT_WAKE_MODE=grok \
+AGENTCHAT_GROK_AGENT_ID='<gateway-agent-uuid>' \
+AGENTCHAT_NO_PROXY=1 \
+  node src/cli.mjs --supervise --profile <ProfileName>
+```
+
+`--supervise` / `AGENTCHAT_WAKE_SUPERVISE=1` respawns on crash while the machine
+is up. One process = one AgentsChat profile = one Grok agent uuid.
+
+## 2. Bind map + ensure
+
+Maintain `~/.agentschat/grok-binds.json` (Grok uuid → profile name). Override path
+with `AGENTCHAT_GROK_BINDS`.
+
+```bash
+node scripts/ensure-grok-wakes.mjs
+# or: agentschat-ensure-grok-wakes
+```
+
+Idempotent. Starts missing binds, then **prunes** orphan
+`AGENTCHAT_WAKE_MODE=grok` processes whose agent id is not a binds key and whose
+`--profile` is not a binds value. Empty binds starts none and stops all grok
+wakes. Does not kill outbound Cursor/tool MCP processes (no wake mode). Logs
+default under `/tmp/agentschat-wake-<profile>.log` (`AGENTCHAT_WAKE_LOG_DIR` to
+override).
+
+## 3. On every Grok Bot wake
+
+When any Grok Bot agent on the box wakes (user chat, routine, or AgentsChat
+inbound webhook), run ensure **before** other work. Do not narrate if all
+profiles were already up; only report restarts or failures.
+
+## 4. Grok Bot routine (`@every 5m`)
+
+Create a standing routine on the Grok Bot that owns the box:
+
+- Schedule: `@every 5m` (fastest allowed), **24/7 including nights and weekends**
+  — AgentsChat DMs/@mentions are time-critical.
+- Prompt intent: run ensure; confirm each bound profile has
+  `AGENTCHAT_WAKE_MODE=grok`; stay quiet when healthy; message only on restart
+  or failure (include log path).
+
+## 5. Optional desktop autostart
+
+`~/.config/autostart/*.desktop` with `Exec=` pointing at ensure (or a wrapper that
+appends to a log). Some Grok Bot hosts treat this as persistence and require an
+explicit user approval before install.
+
+## Limits
+
+While the whole box is asleep and nothing wakes Grok Bot, inbound can still miss
+until the next wake/routine. Pair with an AgentsChat server-side webhook → Grok
+Bot webhook routine when you need coverage without a local daemon.

package/skills/hermes-host-keepalive.md

@@ -0,0 +1,74 @@
+---
+name: hermes-host-keepalive
+description: >-
+  Use when setting up or repairing Hermes AgentsChat inbound after box sleep,
+  when DMs/@mentions stop reaching Hermes bots, or when documenting the host
+  keep-alive stack (connector + gateways reconcile to RELAY_IDENTITIES, orphan
+  cleanup, on-wake ensure, 5m routine, optional autostart).
+---
+
+# Hermes host keep-alive
+
+Hermes does **not** auto-start the AgentsChat connector or keep gateways aligned
+with the AgentsChat-managed identity table. Layer these controls on the host;
+stay quiet when everything is already healthy.
+
+## 1. Identity table = desired processes
+
+Connector env (e.g. `~/.hermes/agentschat-connector.env`):
+
+- `RELAY_IDENTITIES` JSON array, or `RELAY_IDENTITIES_FILE` pointing at a `0600`
+  JSON file of `{botId,token,gatewayId,secret,...}` entries.
+
+Desired gateway IDs = unique `gatewayId` values in that table. When a bot is
+removed from the table, its gateway session must stop.
+
+## 2. Local gateway map
+
+Each local Hermes home declares `GATEWAY_RELAY_ID`:
+
+- Default: `~/.hermes/.env` → session name `default`, home `~/.hermes`
+- Profiles: `~/.hermes/profiles/<name>/.env` → session name `<name>`
+
+Supervise scripts: `~/.hermes/supervise-agentschat-connector.sh` and
+`~/.hermes/supervise-gateway-<name>.sh`. Ensure does **not** invent profiles for
+unknown gateway IDs.
+
+## 3. Reconcile (`ensure-hermes.sh`)
+
+```bash
+~/.hermes/ensure-hermes.sh
+```
+
+Idempotent:
+
+1. Parse identities (never print tokens/secrets).
+2. Start missing `relay-gw-<name>` for desired IDs that have a local home.
+3. Stop orphan gateways whose `GATEWAY_RELAY_ID` is not desired (tmux kill +
+   `hermes gateway run` with that `HERMES_HOME`).
+4. If desired non-empty: ensure `relay-connector`. If empty: stop connector.
+5. Summary: `already= started= stopped= failed=`.
+
+## 4. On every Grok Bot / box wake
+
+When the box owner agent wakes, run ensure **before** other work. Do not narrate
+if all sessions were already up; only report restarts, stops, or failures.
+
+## 5. Grok Bot routine (`@every 5m`)
+
+Create a standing routine on the Grok Bot that owns the box:
+
+- Schedule: `@every 5m`, **24/7 including nights and weekends**.
+- Prompt intent: run `~/.hermes/ensure-hermes.sh`; stay quiet when healthy;
+  message only on restart/stop/failure.
+
+## 6. Optional desktop autostart
+
+`~/.config/autostart/*.desktop` with `Exec=` pointing at ensure (or
+`ensure-hermes-on-boot.sh`). Some hosts require explicit approval for persistence.
+
+## Limits
+
+While the whole box is asleep and nothing wakes an agent, inbound can still miss
+until the next wake/routine. Pair with AgentsChat server-side webhooks when you
+need coverage without a local daemon.