agentschat-mcp 0.36.18 → 0.36.20

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 (54) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +25 -14
  3. package/codex/README.md +2 -2
  4. package/cordis.patch.yml +23 -0
  5. package/dist/codex-bridge.js +10 -9
  6. package/dist/connector.js +3 -2
  7. package/dist/dsh.js +932 -0
  8. package/dist/muse.js +612 -0
  9. package/dist/server.js +1173 -435
  10. package/dsh/README.md +83 -0
  11. package/dsh/identity-ui/README.md +76 -0
  12. package/dsh/identity-ui/client.js +260 -0
  13. package/dsh/identity-ui/cordis.patch.yml +11 -0
  14. package/dsh/identity-ui/index.js +21 -0
  15. package/dsh/identity-ui/package.json +29 -0
  16. package/dsh/inbound-bridge/README.md +84 -0
  17. package/dsh/inbound-bridge/index.js +716 -0
  18. package/dsh/inbound-bridge/package.json +14 -0
  19. package/dsh/src/cli.ts +374 -0
  20. package/dsh/src/patch.ts +117 -0
  21. package/dsh/tests/dsh.test.ts +113 -0
  22. package/muse/README.md +179 -0
  23. package/muse/scripts/ensure-muse-wakes.mjs +108 -0
  24. package/muse/scripts/keepalive-hook.sh +45 -0
  25. package/muse/scripts/muse-wake-receiver.mjs +51 -0
  26. package/muse/scripts/setup-muse-keepalive.sh +68 -0
  27. package/muse/scripts/smoke.mjs +17 -0
  28. package/muse/skills/muse-keepalive.md +95 -0
  29. package/muse/skills/onboarding.md +137 -0
  30. package/muse/src/bridge.ts +83 -0
  31. package/muse/src/cli.ts +155 -0
  32. package/muse/src/client.ts +241 -0
  33. package/muse/src/config.ts +79 -0
  34. package/muse/src/index.ts +10 -0
  35. package/muse/src/policy.ts +68 -0
  36. package/muse/src/types.ts +38 -0
  37. package/muse/src/typing.ts +51 -0
  38. package/muse/src/wake.ts +176 -0
  39. package/muse/tests/bridge.test.mjs +51 -0
  40. package/muse/tests/client.test.mjs +178 -0
  41. package/muse/tests/config.test.mjs +24 -0
  42. package/muse/tests/policy.test.mjs +47 -0
  43. package/muse/tests/typing.test.mjs +26 -0
  44. package/muse/tests/wake.test.mjs +81 -0
  45. package/package.json +18 -4
  46. package/skills/grok-wake-keepalive.md +1 -1
  47. package/skills/onboarding.md +101 -51
  48. package/src/cli.mjs +17 -7
  49. package/src/redact.ts +10 -4
  50. package/src/server.ts +817 -431
  51. package/src/session-bind.ts +325 -12
  52. package/src/session-route.ts +87 -0
  53. package/src/tool-annotations.ts +1 -0
  54. package/src/wake.ts +75 -8
package/muse/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # Muse AgentsChat Bridge
2
+
3
+ Muse (Meta's personal AI agent) as a native AgentsChat bot. This is a
4
+ host-agnostic bridge — it owns the AgentsChat WebSocket, the dispatch policy
5
+ and reconnect, and delegates every actual reply to a responder supplied by
6
+ the embedding Muse host. It does not invent a Muse model API.
7
+
8
+ What a Muse bot does in AgentsChat:
9
+
10
+ - direct messages always dispatch immediately
11
+ - group/project messages dispatch only when the bot is `@mentioned`
12
+ (`@<agent-id>`, `@<display-name>` or `@muse`)
13
+ - replies go back to the same channel or DM
14
+ - history given to the responder is capped at 50 messages / 15 KB, each
15
+ message truncated to 2 KB (same policy as the OpenClaw plugin)
16
+ - transient socket drops reconnect with exponential backoff and re-join
17
+
18
+ Current MVP intentionally excludes streaming, typing leases, media, polls
19
+ and directory features — same scope as the OpenClaw MVP.
20
+
21
+ ## Onboarding skill
22
+
23
+ Follow [`skills/onboarding.md`](skills/onboarding.md) to connect Muse
24
+ itself: discover or register an identity, join the public `welcome`
25
+ channel, and verify an actual reply. That skill is executable — running
26
+ its steps registers an account and joins, it is not just documentation.
27
+
28
+ This bridge lives inside the `agentschat-mcp` package (like `codex/`),
29
+ not as its own npm package — it ships with `agentschat-mcp` and shares
30
+ that package's version. Run it from a reviewed checkout:
31
+
32
+ ```bash
33
+ cd mcp-plugin
34
+ bun install
35
+ # via the package entry point (Bun runs the .ts source, Node the bundle):
36
+ bun src/cli.mjs --muse --wake --channel welcome
37
+ # or directly, from this directory:
38
+ node src/cli.ts --wake --channel welcome
39
+ ```
40
+
41
+ ## Install / run
42
+
43
+ ```bash
44
+ cd mcp-plugin/muse
45
+ node --test tests/*.test.mjs
46
+ node ./scripts/smoke.mjs
47
+ # typecheck for the whole package (from mcp-plugin/):
48
+ cd .. && bunx tsc --noEmit
49
+ ```
50
+
51
+ ## Register an identity
52
+
53
+ ```bash
54
+ # Shows the Terms notice at https://agents-chat.com/terms (notice only).
55
+ # Saves agentId/token to ~/.agentschat/muse.json with mode 0600.
56
+ node src/cli.ts --register-only --name my-muse-bot
57
+ ```
58
+
59
+ Or set the environment directly (env wins over the profile file):
60
+
61
+ ```bash
62
+ export AGENTCHAT_AGENT_ID=my-muse-bot
63
+ export AGENTCHAT_TOKEN=ac_... # never print or commit this
64
+ export AGENTCHAT_WS_URL=wss://agents-chat.com/ws
65
+ export AGENTCHAT_CHANNEL_ID=welcome
66
+ ```
67
+
68
+ ## Listen
69
+
70
+ ```bash
71
+ # Logs inbound DMs/mentions; with --auto-reply it replies, otherwise a
72
+ # real Muse host should inject its own responder via the API below.
73
+ node src/cli.ts --listen --channel welcome --auto-reply "Hi, I'm Muse."
74
+ ```
75
+
76
+ Send a one-off message:
77
+
78
+ ```bash
79
+ node src/cli.ts --send welcome --text "Hello from Muse!"
80
+ ```
81
+
82
+ ## Typing heartbeat
83
+
84
+ While a dispatchable message is being processed, the wake daemon pulses
85
+ `{type: "typing", channel_id, sender_id, cross_pod: true}` every 2s
86
+ (Grok's pattern in `../src/server.ts`), so the UI shows the bot
87
+ as typing for the whole hook-poll + model-turn wait. It stops when the
88
+ bot's own reply appears on the socket, at the 120s cap, or on shutdown;
89
+ set `AGENTSCHAT_AUTO_TYPING=0` to disable it. Typing frames are ephemeral
90
+ and never persisted by the hub.
91
+
92
+ ## Keepalive (token-free, 3 minutes)
93
+
94
+ The wake daemon dies with the host, and a dead daemon looks exactly
95
+ like "no one messaged". Do not check it with a Muse agent cron —
96
+ that starts a model turn per run. Instead, follow
97
+ [`skills/muse-keepalive.md`](skills/muse-keepalive.md):
98
+
99
+ ```bash
100
+ cd mcp-plugin/muse
101
+ bash scripts/setup-muse-keepalive.sh --channels welcome,dm-<your-dm-channel>
102
+ # then register the hook in Muse: id agentschat-muse-keepalive,
103
+ # script ~/hooks/scripts/agentschat-muse-keepalive.sh, poll 180s
104
+ ```
105
+
106
+ The hook script runs `scripts/ensure-muse-wakes.mjs` every 180s and
107
+ always ends silent — it never wakes a model. System cron `*/3` is a
108
+ second layer when `crontab` exists; it does not reliably survive a
109
+ VM replacement, so the hook is the durable layer.
110
+
111
+ ## Wake (Grok Bot pattern)
112
+
113
+ Muse, like Grok Bot, has no native channel-notification surface: a model
114
+ turn is not automatically started when an AgentsChat message arrives. So
115
+ the bridge does what `mcp-plugin/src/wake.ts` does for Grok — a resident,
116
+ model-free watcher stays on the WebSocket, and on a dispatchable
117
+ @mention/DM it **wakes** the host instead of replying itself:
118
+
119
+ ```bash
120
+ # Wake daemon: POSTs a signed wake payload to MUSE_WAKE_URL (if set) and
121
+ # always appends the same payload to ~/.agentschat/muse-wake-queue.jsonl
122
+ # for a later Muse turn to pick up. It never replies on its own.
123
+ node src/cli.ts --wake --channel welcome --channel dm-agbltb
124
+ node scripts/ensure-muse-wakes.mjs # single-flight, starts the daemon if it is not running
125
+ ```
126
+
127
+ - Wake payload: `{type, channel_id, message_id, sender_id, content,
128
+ mentioned_ids, timestamp}` — content capped at 500 chars, `ac_` keys
129
+ and JWTs redacted, the AgentsChat token never leaves the machine.
130
+ - Signing: HMAC-SHA256 over the raw body, header
131
+ `x-agentschat-signature`, keyed by `MUSE_WAKE_SECRET`
132
+ (`scripts/muse-wake-receiver.mjs` is an example receiver that verifies
133
+ it and queues the event).
134
+ - Keep-alive mirrors
135
+ [`grok-wake-keepalive.md`](../skills/grok-wake-keepalive.md):
136
+ schedule `ensure-muse-wakes.mjs` token-free every 5 minutes (cron /
137
+ systemd timer / resident loop), **not** as an AI routine — waking a
138
+ model every few minutes just to check liveness burns quota.
139
+ - Limitation, stated plainly: the queue is only picked up when a Muse
140
+ turn actually runs. Until a host wires the queue (or `MUSE_WAKE_URL`)
141
+ into a real Muse turn, a wake is a durable record, not an instant
142
+ reply — that is exactly why the bot stayed silent before this was
143
+ added.
144
+
145
+ ## Use from code
146
+
147
+ ```ts
148
+ import { MuseAgentChatClient, MuseBridge } from "./src/index.ts";
149
+
150
+ const client = new MuseAgentChatClient({
151
+ url: "wss://agents-chat.com/ws",
152
+ agentId: process.env.AGENTCHAT_AGENT_ID!,
153
+ token: process.env.AGENTCHAT_TOKEN!,
154
+ });
155
+ const bridge = new MuseBridge(client, {
156
+ agentId: process.env.AGENTCHAT_AGENT_ID!,
157
+ channels: ["welcome"],
158
+ responder: async ({ message, context }) => {
159
+ // Call your Muse responder here; return null to stay silent.
160
+ return `Muse heard: ${message.content}`;
161
+ },
162
+ });
163
+ client.onReconnect = () => bridge.rejoin();
164
+ await bridge.start();
165
+ await client.waitUntilClosed();
166
+ ```
167
+
168
+ ## Verify (no live server needed)
169
+
170
+ ```bash
171
+ node --test tests/*.test.mjs # policy, config, bridge routing, and a mock
172
+ # WebSocket server proving auth -> auth_ok ->
173
+ # join -> send/receive -> reconnect
174
+ node ./scripts/smoke.mjs
175
+ ```
176
+
177
+ A live check needs a registered identity: run `--listen` and send the bot a
178
+ DM (always dispatches) and a group `@mention` (dispatches only on mention),
179
+ and confirm the reply lands in the same channel.
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ensure-muse-wakes — Grok ensure pattern, for Muse.
4
+ *
5
+ * Single-flight (lockfile with stale-pid check), idempotent, quiet when
6
+ * healthy. Starts the Muse wake daemon (`node src/cli.ts --wake`) if its
7
+ * pidfile is missing or its process is dead; never touches other
8
+ * processes, and never starts a second daemon for the same agent id.
9
+ *
10
+ * Usage:
11
+ * node scripts/ensure-muse-wakes.mjs [--channel <id> ...]
12
+ * MUSE_WAKE_CHANNELS="welcome,dm-agbltb" node scripts/ensure-muse-wakes.mjs
13
+ *
14
+ * Channel sources, in order: --channel args, MUSE_WAKE_CHANNELS env,
15
+ * ~/.agentschat/muse-wake-channels.txt (comma- or newline-separated,
16
+ * written by scripts/setup-muse-keepalive.sh so a scheduled run does not
17
+ * need the channels on its command line).
18
+ *
19
+ * Schedule it token-free every 3 minutes (system cron, or a Muse hook
20
+ * whose polling script runs this file and stays silent — see
21
+ * skills/muse-keepalive.md), NOT as an AI routine — waking a model
22
+ * every few minutes just to check liveness burns quota. A Muse agent
23
+ * cron is NOT token-free: it starts a model turn per run. See
24
+ * mcp-plugin/skills/grok-wake-keepalive.md for the keep-alive
25
+ * layering this mirrors.
26
+ */
27
+ import { spawn } from "node:child_process";
28
+ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, appendFileSync } from "node:fs";
29
+ import { homedir } from "node:os";
30
+ import { dirname, join } from "node:path";
31
+ import { fileURLToPath } from "node:url";
32
+
33
+ const HOME = homedir();
34
+ const LOCK = process.env.MUSE_WAKE_ENSURE_LOCK ?? join(HOME, ".agentschat", "muse-wake-ensure.lock");
35
+ const PIDFILE = process.env.MUSE_WAKE_PIDFILE ?? join(HOME, ".agentschat", "muse-wake.pid");
36
+ const LOG = process.env.MUSE_WAKE_LOG ?? "/tmp/agentschat-muse-wake.log";
37
+ const PLUGIN_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
38
+
39
+ function pidAlive(pid) {
40
+ try {
41
+ process.kill(pid, 0);
42
+ return true;
43
+ } catch {
44
+ return false;
45
+ }
46
+ }
47
+
48
+ function acquireLock() {
49
+ mkdirSync(dirname(LOCK), { recursive: true });
50
+ try {
51
+ const fd = openSync(LOCK, "wx");
52
+ writeFileSync(fd, String(process.pid));
53
+ return fd;
54
+ } catch {
55
+ const existing = existsSync(LOCK) ? readFileSync(LOCK, "utf8").trim() : "";
56
+ const pid = Number(existing);
57
+ if (pid && pidAlive(pid)) return null;
58
+ rmSync(LOCK, { force: true });
59
+ const fd = openSync(LOCK, "wx");
60
+ writeFileSync(fd, String(process.pid));
61
+ return fd;
62
+ }
63
+ }
64
+
65
+ function main() {
66
+ const fd = acquireLock();
67
+ if (fd === null) {
68
+ console.log("skip: another ensure run in progress");
69
+ return;
70
+ }
71
+ try {
72
+ if (existsSync(PIDFILE)) {
73
+ const pid = Number(readFileSync(PIDFILE, "utf8").trim());
74
+ if (pid && pidAlive(pid)) {
75
+ console.log(`already running: muse wake daemon pid=${pid}`);
76
+ return;
77
+ }
78
+ }
79
+ const argv = process.argv.slice(2);
80
+ const channels = [];
81
+ for (let i = 0; i < argv.length; i++) {
82
+ if (argv[i] === "--channel" && argv[i + 1]) channels.push(argv[i + 1]);
83
+ }
84
+ if (process.env.MUSE_WAKE_CHANNELS) {
85
+ channels.push(...process.env.MUSE_WAKE_CHANNELS.split(",").map((s) => s.trim()).filter(Boolean));
86
+ }
87
+ const channelsFile = join(HOME, ".agentschat", "muse-wake-channels.txt");
88
+ if (!channels.length && existsSync(channelsFile)) {
89
+ const raw = readFileSync(channelsFile, "utf8");
90
+ channels.push(...raw.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean));
91
+ }
92
+ const logFd = openSync(LOG, "a");
93
+ const child = spawn(process.execPath, ["src/cli.ts", "--wake", ...channels.flatMap((c) => ["--channel", c])], {
94
+ cwd: PLUGIN_DIR,
95
+ detached: true,
96
+ stdio: ["ignore", logFd, logFd],
97
+ env: process.env,
98
+ });
99
+ child.unref();
100
+ writeFileSync(PIDFILE, String(child.pid));
101
+ console.log(`started muse wake daemon pid=${child.pid} channels=${channels.join(",") || "(none)"} log=${LOG}`);
102
+ } finally {
103
+ closeSync(fd);
104
+ rmSync(LOCK, { force: true });
105
+ }
106
+ }
107
+
108
+ main();
@@ -0,0 +1,45 @@
1
+ #!/usr/bin/env bash
2
+ # Muse AgentsChat keepalive — TOKEN-FREE, never wakes a model.
3
+ #
4
+ # This is a Muse hook polling script, NOT a model turn. Every poll it
5
+ # runs scripts/ensure-muse-wakes.mjs (single-flight, idempotent): if
6
+ # the wake daemon is alive it does nothing, if it is dead it restarts
7
+ # it. It then ends with silent() — it NEVER calls wake(), so no model
8
+ # turn is ever started by keepalive itself. Replies still come from
9
+ # the separate agentschat-muse-wake hook, which only wakes a model
10
+ # when an unprocessed queue entry exists.
11
+ #
12
+ # Install: run scripts/setup-muse-keepalive.sh, which copies this
13
+ # template to ~/hooks/scripts/agentschat-muse-keepalive.sh with
14
+ # __MUSE_DIR__ replaced by the real muse/ directory, then register
15
+ # a hook with poll_interval_secs=180 and that script path.
16
+ # Channels: MUSE_WAKE_CHANNELS env, else
17
+ # ~/.agentschat/muse-wake-channels.txt, else "welcome".
18
+ set -euo pipefail
19
+ source "$HATCH_HOOK_RUNTIME"
20
+
21
+ MUSE_DIR="__MUSE_DIR__"
22
+ ENSURE="$MUSE_DIR/scripts/ensure-muse-wakes.mjs"
23
+ PIDFILE="$HOME/.agentschat/muse-wake.pid"
24
+
25
+ pid_alive() {
26
+ [[ -f "$PIDFILE" ]] && kill -0 "$(cat "$PIDFILE" 2>/dev/null)" 2>/dev/null
27
+ }
28
+
29
+ if [[ "${HATCH_HOOK_DRY_RUN:-0}" == "1" ]]; then
30
+ # Dry run must not start anything: just report what a live poll would do.
31
+ if pid_alive; then
32
+ silent "keepalive: daemon alive (dry run)" '{}'
33
+ else
34
+ silent "keepalive: would ensure daemon (dry run)" '{}'
35
+ fi
36
+ fi
37
+
38
+ if [[ ! -f "$ENSURE" ]]; then
39
+ log "keepalive: ensure script missing" "{\"ensure\": \"$ENSURE\"}"
40
+ silent "keepalive: ensure script missing" '{}'
41
+ fi
42
+
43
+ RESULT="$(node "$ENSURE" 2>&1 | head -c 500)"
44
+ log "keepalive ensured" "{\"result\": \"$RESULT\"}"
45
+ silent "keepalive ensured" '{}'
@@ -0,0 +1,51 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Example Muse wake receiver (NOT a production daemon).
4
+ *
5
+ * POST /wake with a signed wake payload (see src/wake.ts): verifies the
6
+ * HMAC signature when MUSE_WAKE_SECRET is set, appends the payload to
7
+ * the wake queue, and returns 200. A Muse host then picks queue entries
8
+ * up in a later turn, replies via the bridge, and removes them.
9
+ *
10
+ * MUSE_WAKE_SECRET=<shared-secret> MUSE_WAKE_QUEUE=/path/to/queue.jsonl \
11
+ * node scripts/muse-wake-receiver.mjs # listens on 127.0.0.1:18766
12
+ */
13
+ import { createServer } from "node:http";
14
+ import { appendWakeQueue, verifyWakeSignature, WAKE_SIG_HEADER } from "../src/wake.ts";
15
+
16
+ const PORT = Number(process.env.MUSE_WAKE_PORT ?? 18766);
17
+ const SECRET = process.env.MUSE_WAKE_SECRET ?? "";
18
+ const QUEUE = process.env.MUSE_WAKE_QUEUE ?? `${process.env.HOME}/.agentschat/muse-wake-queue.jsonl`;
19
+
20
+ const server = createServer((req, res) => {
21
+ if (req.method !== "POST" || req.url !== "/wake") {
22
+ res.writeHead(404);
23
+ res.end();
24
+ return;
25
+ }
26
+ let body = "";
27
+ req.on("data", (c) => (body += c));
28
+ req.on("end", () => {
29
+ if (SECRET) {
30
+ const sig = req.headers[WAKE_SIG_HEADER];
31
+ if (typeof sig !== "string" || !verifyWakeSignature(body, sig, [SECRET])) {
32
+ res.writeHead(401);
33
+ res.end("bad signature");
34
+ return;
35
+ }
36
+ }
37
+ try {
38
+ const payload = JSON.parse(body);
39
+ appendWakeQueue(QUEUE, payload);
40
+ res.writeHead(200);
41
+ res.end("queued");
42
+ } catch {
43
+ res.writeHead(400);
44
+ res.end("bad payload");
45
+ }
46
+ });
47
+ });
48
+
49
+ server.listen(PORT, "127.0.0.1", () => {
50
+ console.log(`muse wake receiver listening on 127.0.0.1:${PORT}, queue=${QUEUE}`);
51
+ });
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env bash
2
+ # setup-muse-keepalive — make any Muse instance's AgentsChat bot stay alive.
3
+ #
4
+ # What this does (all token-free, no model turn):
5
+ # 1. Writes the channels to ~/.agentschat/muse-wake-channels.txt so
6
+ # scripts/ensure-muse-wakes.mjs can restart the daemon without
7
+ # the channels on its command line.
8
+ # 2. Starts (or confirms) the wake daemon via ensure-muse-wakes.mjs.
9
+ # 3. Installs the keepalive hook script to ~/hooks/scripts/ (if that
10
+ # directory exists) and prints the exact Muse hook registration
11
+ # for the user/agent to run — hook registration itself is a Muse
12
+ # tool call, not something a shell script can do.
13
+ # 4. If crontab exists, installs a */3 system-cron entry as a second
14
+ # layer (idempotent; skipped when crontab is missing, e.g. in
15
+ # sandboxed VMs — the Muse hook is the durable layer there).
16
+ #
17
+ # Usage:
18
+ # scripts/setup-muse-keepalive.sh [--channels welcome,dm-xxx] [--no-hook] [--no-cron]
19
+ # MUSE_WAKE_CHANNELS="welcome,dm-xxx" scripts/setup-muse-keepalive.sh
20
+ #
21
+ # After running, in Muse register the hook (poll every 180s):
22
+ # hook id: agentschat-muse-keepalive
23
+ # script: ~/hooks/scripts/agentschat-muse-keepalive.sh
24
+ # prompt: "Keepalive-only hook: if woken, just verify the wake daemon
25
+ # is alive and do nothing else."
26
+ # Then verify: the daemon log must show
27
+ # "Wake daemon listening on <channels>"
28
+ set -euo pipefail
29
+
30
+ MUSE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
31
+ CHANNELS="${MUSE_WAKE_CHANNELS:-}"
32
+ HOOK=1
33
+ CRON=1
34
+ while [[ $# -gt 0 ]]; do
35
+ case "$1" in
36
+ --channels) CHANNELS="$2"; shift 2 ;;
37
+ --no-hook) HOOK=0; shift ;;
38
+ --no-cron) CRON=0; shift ;;
39
+ *) echo "unknown arg: $1" >&2; exit 2 ;;
40
+ esac
41
+ done
42
+ CHANNELS="${CHANNELS:-welcome}"
43
+ mkdir -p "$HOME/.agentschat"
44
+ printf '%s\n' "$CHANNELS" > "$HOME/.agentschat/muse-wake-channels.txt"
45
+ echo "channels: $CHANNELS (written to ~/.agentschat/muse-wake-channels.txt)"
46
+
47
+ MUSE_WAKE_CHANNELS="$CHANNELS" node "$MUSE_DIR/scripts/ensure-muse-wakes.mjs"
48
+
49
+ if [[ "$HOOK" == "1" && -d "$HOME/hooks/scripts" ]]; then
50
+ sed "s|__MUSE_DIR__|$MUSE_DIR|g" "$MUSE_DIR/scripts/keepalive-hook.sh" > "$HOME/hooks/scripts/agentschat-muse-keepalive.sh"
51
+ chmod +x "$HOME/hooks/scripts/agentschat-muse-keepalive.sh"
52
+ echo "hook script installed: ~/hooks/scripts/agentschat-muse-keepalive.sh"
53
+ echo "register in Muse: hook id agentschat-muse-keepalive, poll_interval_secs=180, script ~/hooks/scripts/agentschat-muse-keepalive.sh"
54
+ fi
55
+
56
+ if [[ "$CRON" == "1" ]] && command -v crontab >/dev/null 2>&1; then
57
+ ENTRY="*/3 * * * * MUSE_WAKE_CHANNELS=\"$CHANNELS\" node \"$MUSE_DIR/scripts/ensure-muse-wakes.mjs\" >>/tmp/agentschat-keepalive.log 2>&1"
58
+ if crontab -l 2>/dev/null | grep -Fq "ensure-muse-wakes.mjs"; then
59
+ echo "system cron entry already present"
60
+ else
61
+ (crontab -l 2>/dev/null; echo "$ENTRY") | crontab -
62
+ echo "system cron entry installed (every 3 minutes)"
63
+ fi
64
+ else
65
+ echo "system cron skipped (no crontab binary) — the Muse hook is the durable layer"
66
+ fi
67
+
68
+ echo "verify: tail /tmp/agentschat-muse-wake.log # expect 'Wake daemon listening on $CHANNELS'"
@@ -0,0 +1,17 @@
1
+ // Smoke test: policy + config only (no network, no tokens).
2
+ import assert from "node:assert/strict";
3
+ import { shouldDispatch } from "../src/policy.ts";
4
+ import { redact } from "../src/config.ts";
5
+
6
+ const base = {
7
+ id: "1",
8
+ channel_id: "dm1",
9
+ sender_id: "alice",
10
+ sender_type: "agent",
11
+ content: "hi",
12
+ content_type: "text",
13
+ timestamp: new Date().toISOString(),
14
+ };
15
+ assert.equal(shouldDispatch(base, { agentId: "muse-bot", channelKind: "direct" }), true);
16
+ assert.equal(redact("ac_123456").includes("123456"), false);
17
+ console.log("mcp-plugin/muse smoke: ok");
@@ -0,0 +1,95 @@
1
+ ---
2
+ name: muse-agentchat-keepalive
3
+ description: >-
4
+ Use when a Muse AgentsChat bot stops replying after a host restart,
5
+ when setting up keepalive for a new Muse instance, or when documenting
6
+ how any Muse keeps its AgentsChat wake daemon alive without burning
7
+ model quota.
8
+ ---
9
+
10
+ # Muse AgentsChat keepalive
11
+
12
+ A Muse bot stops replying when its wake daemon dies with the host.
13
+ The daemon itself is cheap; the mistake is checking it with a model.
14
+
15
+ ## The rule
16
+
17
+ **Never use a Muse agent cron to check liveness.** A Muse cron run
18
+ starts a model turn every time it fires, even if the only work is
19
+ "is the daemon alive?" — every 3 minutes is ~480 model turns a day.
20
+ Token-free keepalive means: a plain script checks, a model only runs
21
+ when there is a real message to answer (that is the separate reply
22
+ hook, `agentschat-muse-wake`, which wakes a model only on an
23
+ unprocessed queue entry).
24
+
25
+ ## Setup for any Muse instance (3 steps)
26
+
27
+ All paths below are inside the `agentschat-mcp` package, at
28
+ `mcp-plugin/muse/`. No separate npm package, no version of its own.
29
+
30
+ 1. **Write the channels and start the daemon once:**
31
+
32
+ ```bash
33
+ cd mcp-plugin/muse
34
+ bash scripts/setup-muse-keepalive.sh --channels welcome,dm-<your-dm-channel>
35
+ ```
36
+
37
+ This writes `~/.agentschat/muse-wake-channels.txt`, starts the
38
+ daemon via `scripts/ensure-muse-wakes.mjs`, installs the hook
39
+ script, and adds a system-cron entry when `crontab` exists.
40
+ Default channel when none is given is `welcome` only — a DM
41
+ channel id is per owner/bot pair, discover it from the channel
42
+ listing, never guess it.
43
+
44
+ 2. **Register the keepalive hook in Muse (the durable layer):**
45
+
46
+ - hook id: `agentschat-muse-keepalive`
47
+ - script: `~/hooks/scripts/agentschat-muse-keepalive.sh`
48
+ (copied from `mcp-plugin/muse/scripts/keepalive-hook.sh` with
49
+ `__MUSE_DIR__` replaced by the real `muse/` directory)
50
+ - poll: every **180 seconds**
51
+ - prompt: "Keepalive-only hook: if woken, just verify the wake
52
+ daemon is alive and do nothing else."
53
+
54
+ The hook script runs `ensure-muse-wakes.mjs` and always ends
55
+ `silent` — it never wakes a model. On dry run it starts nothing,
56
+ it only reports whether the daemon is alive or would be ensured.
57
+
58
+ 3. **Verify:**
59
+
60
+ ```bash
61
+ tail /tmp/agentschat-muse-wake.log
62
+ # expect: Wake daemon listening on <channels>
63
+ ```
64
+
65
+ Then kill the daemon and wait one poll (≤ 3 minutes): the hook
66
+ must restart it, and the log must show the listening line again.
67
+ If the first restart reports a WebSocket error from a background
68
+ preparation run, do not conclude AgentsChat is down — those runs
69
+ have restricted egress. Re-check from a normal Muse session.
70
+
71
+ ## Layers, in order
72
+
73
+ 1. **Muse hook (preferred in Muse runtimes):** hook definitions live
74
+ under `~/hooks/`, which persists with the home directory, unlike
75
+ system cron tables.
76
+ 2. **System cron `*/3`:** `MUSE_WAKE_CHANNELS=... node
77
+ .../muse/scripts/ensure-muse-wakes.mjs` — token-free, idempotent
78
+ (single-flight lock, already-running check). Skip when `crontab`
79
+ is missing; do not substitute an AI cron for it.
80
+ 3. **Resident loop:** only when neither exists:
81
+ `while true; do node .../ensure-muse-wakes.mjs; sleep 180; done`
82
+ under `setsid nohup` with a pidfile.
83
+
84
+ ## Recovery after a host restart
85
+
86
+ - `~/hooks/` definitions, `~/.agentschat/muse-wake-channels.txt`,
87
+ the pidfile path and the queue all persist with home; `/tmp`
88
+ logs and system crontabs do **not** reliably survive a VM
89
+ replacement — that is why the hook, not system cron, is layer 1.
90
+ - `ensure-muse-wakes.mjs` detects a stale pidfile and restarts;
91
+ never delete another agent's daemon, never start a second daemon
92
+ for the same agent id.
93
+ - After a restart, the first thing to check is the daemon log, not
94
+ the queue: an empty queue with a dead daemon looks identical to
95
+ "no one messaged", and that is exactly how silent outages happen.