murmur-it 0.2.3 → 0.2.5
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.
- package/CHANGELOG.md +37 -1
- package/README.md +5 -5
- package/adapters/hummin/murmur.ts +2 -2
- package/adapters/opencode/murmur.ts +2 -2
- package/dist/broker.js +26 -16
- package/dist/cli.js +1 -1
- package/dist/client.js +11 -6
- package/dist/core.js +10 -9
- package/dist/install.js +1 -1
- package/dist/mcp.js +77 -30
- package/dist/native.js +2 -5
- package/package.json +7 -7
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,39 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to murmur are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
|
|
4
4
|
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [0.2.5] - 2026-10-21
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- A `choice` verdict for picking one of the options a question offers, with the body starting `CHOICE <option>`. Before, a plain pick had to go out as `AGREE` or `DISAGREE`, and a `DISAGREE` read as a conflict when there was none. `murmur_wait` and `collect` report it like the other verdicts, and `verdictTally` has a `choice` count. The MCP instructions tell askers to ask for a `CHOICE` reply when they offer options, and the reply tools (MCP, CLI, the slash command and the hummin and opencode adapters) describe and accept it.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- The MCP server reconnects when its broker connection drops, instead of exiting. A broker restart or upgrade no longer needs `/mcp` in every session: the server connects again (the `murmur` bin starts a broker when none answers, unless `MURMUR_AUTOSTART=0`), registers as the same session, and its tools keep working. It tries 20 times, 250 ms apart (a try that starts a broker waits up to 3 s for it), and ends when no broker answers or when its stdin closes, as before. A server whose stdin closes during the tries starts no new try after that (a try already under way finishes), so a session that is gone stops starting brokers.
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- A `murmur` command that a CLI sandbox blocks from the broker socket no longer says "murmur broker is down; start it with: murmur serve", and no longer starts a broker. Codex's default `read-only` and `workspace-write` sandboxes deny Unix sockets (`connect EPERM`), so a codex session that replied with `murmur reply` from its shell got that message while the broker was up. It now fails with `socket_denied` and tells the agent to use the murmur tools. Before, the broker it started took the denied probe for a stale socket and, when the murmur home was writable inside the sandbox, removed the live broker's socket, which cut that broker off from every new client. A broker now removes a socket file only when the probe is refused or the file is not a socket.
|
|
20
|
+
|
|
21
|
+
## [0.2.4] - 2026-10-21
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- Requires Node 22 or newer (`engines` was `>=20`). Node 20 reached end of life on 2026-04-30, and vitest 5 needs Node 22.12 to run the tests, so CI now runs on Node 22 and 24 instead of 20 and 22.
|
|
26
|
+
- Dependencies: zod 4 (runtime), and for development TypeScript 7, `@types/node` 26, vitest and `@vitest/coverage-v8` 5 and `actions/setup-node` 7.1.0.
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- One reply that resolves two waits on the same thread answers each wait once. Before, handing over the first wait's replies re-entered the waiter check, which answered the second wait, and the outer loop then answered it again from its stale copy (`src/broker.ts` `checkWaiters`).
|
|
31
|
+
- A reply held for the asker's open `murmur_wait` no longer sends the replier a `queued_delivered` note when the wait hands it over. The note reached the replier as a new turn (a live check woke the replying session a second time for it) although nothing had waited on a session that was down. A reply that was not held for the wait, for example one that stayed queued while the asker's session was closed, still sends the note when a later wait hands it over.
|
|
32
|
+
- The 200 inbox cap (`cap_inbox`) counts only deliveries not yet proven delivered to the recipient's session (queued or sent). It counted delivered ones too, which stay delivered until an ack, so the replies an asker received in waits filled it: after 200 consults every further reply to that asker failed with `cap_inbox`. The unread count in status and inbox is unchanged.
|
|
33
|
+
|
|
34
|
+
### Security
|
|
35
|
+
|
|
36
|
+
- vitest 5 drops the vulnerable test-only dependencies `npm audit` reported (tinypool GHSA-5gmw-xhrv-c9v3 and GHSA-85c8-ppgw-ccpr, critical; vitest and `@vitest/mocker` GHSA-82fw-gwwq-j7x9, moderate). The published package was not affected: `npm audit --omit=dev` found nothing.
|
|
37
|
+
|
|
5
38
|
## [0.2.3] - 2026-10-20
|
|
6
39
|
|
|
7
40
|
### Changed
|
|
@@ -104,9 +137,12 @@ All notable changes to murmur are documented here. The format follows [Keep a Ch
|
|
|
104
137
|
- Limits: send rate, duplicate window, thread and inbox caps.
|
|
105
138
|
- 283 tests at 100 percent lines and branches, and an end-to-end rig that replayed the live 3-peer scenario.
|
|
106
139
|
|
|
140
|
+
[Unreleased]: https://github.com/rennf93/murmur/compare/v0.2.5...HEAD
|
|
141
|
+
[0.2.5]: https://github.com/rennf93/murmur/releases/tag/v0.2.5
|
|
142
|
+
[0.2.4]: https://github.com/rennf93/murmur/releases/tag/v0.2.4
|
|
107
143
|
[0.2.3]: https://github.com/rennf93/murmur/releases/tag/v0.2.3
|
|
108
144
|
[0.2.2]: https://github.com/rennf93/murmur/releases/tag/v0.2.2
|
|
109
145
|
[0.2.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1
|
|
110
146
|
[0.2.1-rc.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1-rc.1
|
|
111
147
|
[0.2.0]: https://github.com/rennf93/murmur/releases/tag/v0.2.0
|
|
112
|
-
[0.1.0]: https://github.com/rennf93/murmur/
|
|
148
|
+
[0.1.0]: https://github.com/rennf93/murmur/commit/294fe18
|
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ This is a CLI demo with simulated peers: `alice` and `bob` are registered by a h
|
|
|
26
26
|
|
|
27
27
|
## Quickstart
|
|
28
28
|
|
|
29
|
-
Requires Node
|
|
29
|
+
Requires Node 22 or newer.
|
|
30
30
|
|
|
31
31
|
```
|
|
32
32
|
npm install -g murmur-it # the package is murmur-it; the command it installs is murmur
|
|
@@ -101,7 +101,7 @@ Delivery states, per recipient: `queued` (stored, nothing left the broker), `sen
|
|
|
101
101
|
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | None: Gemini has no inbound channel | At SessionStart, each prompt (BeforeAgent), and at turn end (AfterAgent continues the turn) | Handed over by the hook |
|
|
102
102
|
| [zcode](https://zcode.z.ai) | None found | At SessionStart, each prompt, and at turn end (Stop continues the turn) | Handed over by the hook (zcode's hook `transcript_path` is a temporary copy, so it cannot serve as proof) |
|
|
103
103
|
|
|
104
|
-
Delivery modes: `push` (default) uses every path above; `notify` stores the message and sends a small batched note; `silent` only stores. A message for a session that is down stays `queued`; when that session comes back its queued messages are pushed (or handed over at its next hook) and the sender gets a `queued_delivered` note. A session that ends with messages still unconsumed triggers a `peer_offline` note to their senders.
|
|
104
|
+
Delivery modes: `push` (default) uses every path above; `notify` stores the message and sends a small batched note; `silent` only stores. A message for a session that is down stays `queued`; when that session comes back its queued messages are pushed (or handed over at its next hook) and the sender gets a `queued_delivered` note (not for a reply held for the asker's open `murmur_wait`: the wait result is its delivery, and the replier is not woken for it). A session that ends with messages still unconsumed triggers a `peer_offline` note to their senders.
|
|
105
105
|
|
|
106
106
|
What a session sees for every message, on every path:
|
|
107
107
|
|
|
@@ -116,7 +116,7 @@ What a session sees for every message, on every path:
|
|
|
116
116
|
- One message, one id, fanned out. Targets are handles and groups: `@name` is always a group; a bare name is a handle, or the group of that name when no peer has that handle. Overlapping groups dedupe.
|
|
117
117
|
- A reply is stored once in the thread and goes only to whoever is waiting for it (the author of the message it answers and the session an owner message was typed in), in the parent's mode; everyone in the thread can read it with `murmur_thread` / `murmur thread`, and `murmur_wait` returns the replies' text. `murmur_thread` with `messageId` (`murmur thread <id> --message <m>`) returns one question and its replies, not the whole thread. To consult several sessions, send once to all of them.
|
|
118
118
|
- Every message has a per-thread monotonic `seq`. `murmur_thread` returns first lines by default, full bodies with `full`, and only newer messages with `sinceSeq`.
|
|
119
|
-
- Verdicts: `agree`, `disagree`, `info`, with the body starting `AGREE`, `DISAGREE` or `
|
|
119
|
+
- Verdicts: `agree`, `disagree`, `info` and `choice`, with the body starting `AGREE`, `DISAGREE`, `INFO` or `CHOICE <option>`. `choice` answers a question that offers options, so picking one does not read as a disagreement. `murmur_wait` returns, for the thread's latest ask, each recipient's state, verdict and reply latency plus their historical p50 and p95, plus the text of the replies addressed to the waiter, either when everyone (or anyone) replied or at the timeout (`timeoutMs: 0` returns now).
|
|
120
120
|
- `references` carries pointers (paths, commits, URLs) so artifacts stay in their repos.
|
|
121
121
|
- Groups: create, list, add, remove, delete. Deleting a group never touches sessions, threads or history.
|
|
122
122
|
|
|
@@ -128,13 +128,13 @@ The human surface, as the owner:
|
|
|
128
128
|
|
|
129
129
|
- `/murmur <group | @group | handle[,more]> <message>`; bare `/murmur` lists peers and groups. In Claude Code and zcode the command file runs `murmur slash --stdin` with the message in a quoted heredoc, so quotes, `$(...)`, backticks and `;` arrive verbatim (Claude Code turns a word-initial `!` into `\!` before the shell sees it; `--claude-escaped` turns it back); the model only shows the output. Hummin's `/murmur` runs with no model turn at all.
|
|
130
130
|
- `murmur send <targets> <body...> [--mode push|notify|silent] [--refs a,b] [--thread <id>] [--as <handle>]`
|
|
131
|
-
- `murmur reply <id> <body...> [--verdict agree|disagree|info] [--refs a,b] [--as <handle>]`
|
|
131
|
+
- `murmur reply <id> <body...> [--verdict agree|disagree|info|choice] [--refs a,b] [--as <handle>]`
|
|
132
132
|
- `murmur status`, `murmur thread <id> [--since <seq>] [--full] [--message <id>]`, `murmur groups [list|create|add|remove|delete] ...`, `murmur name <handle>`, `murmur prune` (removes peers with no session, message, delivery, group membership or live connection, such as v0.1 leftovers, and prints their handles)
|
|
133
133
|
|
|
134
134
|
## Limits
|
|
135
135
|
|
|
136
136
|
- 20 sends per sender per 60 seconds; an identical send (sender, body, recipients) within 60 seconds is rejected as a duplicate. Replies count. In memory; reset on broker restart.
|
|
137
|
-
- 500 messages per thread; 200
|
|
137
|
+
- 500 messages per thread; 200 deliveries per recipient not yet proven delivered to its session (queued or sent); 1 MiB per request line.
|
|
138
138
|
- `murmur_wait`: default 120 s, at most 300 s.
|
|
139
139
|
- Hooks: 10 s hard deadline, up to 10 messages per pull, exit 0 on every failure path.
|
|
140
140
|
- Transcript proof polls for 120 s after a push, then re-checks at that session's next hook event.
|
|
@@ -363,12 +363,12 @@ export default function murmur(pi: ExtensionAPI): void {
|
|
|
363
363
|
name: "murmur_reply",
|
|
364
364
|
label: "Murmur Reply",
|
|
365
365
|
description:
|
|
366
|
-
"Reply to a murmur message; it goes to whoever is waiting for it and anyone in the thread can read it, so start the body with AGREE, DISAGREE or INFO.",
|
|
366
|
+
"Reply to a murmur message; it goes to whoever is waiting for it and anyone in the thread can read it, so start the body with AGREE, DISAGREE, CHOICE <option> (picking one of the options offered) or INFO.",
|
|
367
367
|
promptSnippet: "murmur_reply: answer a [murmur m<id>] message",
|
|
368
368
|
parameters: Type.Object({
|
|
369
369
|
messageId: Type.Number({ description: "Id from the [murmur m<id>] tag" }),
|
|
370
370
|
body: Type.String({ minLength: 1 }),
|
|
371
|
-
verdict: Type.Optional(Type.Union([Type.Literal("agree"), Type.Literal("disagree"), Type.Literal("info")])),
|
|
371
|
+
verdict: Type.Optional(Type.Union([Type.Literal("agree"), Type.Literal("disagree"), Type.Literal("info"), Type.Literal("choice")])),
|
|
372
372
|
references: Type.Optional(Type.Array(Type.String())),
|
|
373
373
|
}),
|
|
374
374
|
async execute(_id, p) {
|
|
@@ -249,11 +249,11 @@ const plugin: Plugin = async ({ client, directory }) => {
|
|
|
249
249
|
ctxCall({ type: 'send', threadId: a.threadId ?? null, to: a.to, body: a.body, references: a.references, mode: a.mode }, ctx),
|
|
250
250
|
}),
|
|
251
251
|
murmur_reply: tool({
|
|
252
|
-
description: 'Reply to a murmur message; it goes to whoever is waiting for it and anyone in the thread can read it, so start the body with AGREE, DISAGREE or INFO.',
|
|
252
|
+
description: 'Reply to a murmur message; it goes to whoever is waiting for it and anyone in the thread can read it, so start the body with AGREE, DISAGREE, CHOICE <option> (picking one of the options offered) or INFO.',
|
|
253
253
|
args: {
|
|
254
254
|
messageId: s.number(),
|
|
255
255
|
body: s.string(),
|
|
256
|
-
verdict: s.enum(['agree', 'disagree', 'info']).optional(),
|
|
256
|
+
verdict: s.enum(['agree', 'disagree', 'info', 'choice']).optional(),
|
|
257
257
|
references: refs,
|
|
258
258
|
},
|
|
259
259
|
execute: (a, ctx) =>
|
package/dist/broker.js
CHANGED
|
@@ -11,7 +11,7 @@ const CLIENT_KINDS = ['mcp', 'cli', 'hook', 'adapter'];
|
|
|
11
11
|
const HOOK_EVENTS = ['session-start', 'prompt', 'stop', 'session-end'];
|
|
12
12
|
const CLI_NAMES = ['claude', 'codex', 'gemini', 'zcode', 'opencode', 'hummin', 'other'];
|
|
13
13
|
const DELIVERY_MODES = ['push', 'notify', 'silent'];
|
|
14
|
-
const VERDICTS = ['agree', 'disagree', 'info'];
|
|
14
|
+
const VERDICTS = ['agree', 'disagree', 'info', 'choice'];
|
|
15
15
|
const GROUP_ACTIONS = ['create', 'list', 'add', 'remove', 'delete'];
|
|
16
16
|
const WAIT_UNTILS = ['all_replied', 'any_replied'];
|
|
17
17
|
// Wire guard: no single request line may exceed 1 MiB.
|
|
@@ -844,14 +844,14 @@ export class Broker {
|
|
|
844
844
|
}
|
|
845
845
|
// queued or sent to delivered, with the queued_delivered notice to the
|
|
846
846
|
// sender when the message had been waiting. False when not applicable.
|
|
847
|
-
markDeliveredHop(messageId, recipient) {
|
|
847
|
+
markDeliveredHop(messageId, recipient, notifySender = true) {
|
|
848
848
|
const message = this.store.messageById(messageId);
|
|
849
849
|
const delivery = this.store.getDeliveries(messageId).find((d) => d.recipient === recipient);
|
|
850
850
|
if (message === null || delivery === undefined || (delivery.state !== 'queued' && delivery.state !== 'sent')) {
|
|
851
851
|
return false;
|
|
852
852
|
}
|
|
853
853
|
this.store.markDelivered(messageId, recipient, Date.now());
|
|
854
|
-
if (delivery.state === 'queued') {
|
|
854
|
+
if (delivery.state === 'queued' && notifySender) {
|
|
855
855
|
this.enqueueNotification(message.sender, {
|
|
856
856
|
kind: 'queued_delivered',
|
|
857
857
|
threadId: message.threadId,
|
|
@@ -997,7 +997,9 @@ export class Broker {
|
|
|
997
997
|
for (const row of this.store.threadMessages(threadId, null)) {
|
|
998
998
|
const delivery = this.store.getDeliveries(row.id).find((d) => d.recipient === handle);
|
|
999
999
|
if (((ask !== null && row.inReplyTo === ask.id) || held?.has(row.id) === true) && delivery?.state === 'queued' && !this.inFlight.has(String(row.id) + ':' + delivery.recipient)) {
|
|
1000
|
-
this
|
|
1000
|
+
// A reply held for this wait never waited on a session that was down:
|
|
1001
|
+
// no queued_delivered notice, which would wake the replier for nothing.
|
|
1002
|
+
this.markDeliveredHop(row.id, delivery.recipient, held?.has(row.id) !== true);
|
|
1001
1003
|
replies.push({ id: row.id, seq: row.seq, sender: row.sender, verdict: row.verdict, body: row.deliveredBody });
|
|
1002
1004
|
}
|
|
1003
1005
|
}
|
|
@@ -1029,7 +1031,8 @@ export class Broker {
|
|
|
1029
1031
|
if (this.stopped) {
|
|
1030
1032
|
return;
|
|
1031
1033
|
}
|
|
1032
|
-
|
|
1034
|
+
// A handover below re-enters checkWaiters and may already have answered this waiter.
|
|
1035
|
+
if (!set.has(waiter) || !this.conditionHolds(threadId, waiter.until)) {
|
|
1033
1036
|
continue;
|
|
1034
1037
|
}
|
|
1035
1038
|
this.removeWaiter(waiter);
|
|
@@ -1061,13 +1064,13 @@ export class Broker {
|
|
|
1061
1064
|
// Never let a timer callback crash the process.
|
|
1062
1065
|
}
|
|
1063
1066
|
}
|
|
1067
|
+
// Only called for a registered waiter: checkWaiters checks set.has, a close
|
|
1068
|
+
// walks conn.waiters, and a timeout fires only while the timer was never cleared.
|
|
1064
1069
|
removeWaiter(waiter) {
|
|
1065
1070
|
const set = this.waiters.get(waiter.threadId);
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
this.waiters.delete(waiter.threadId);
|
|
1070
|
-
}
|
|
1071
|
+
set.delete(waiter);
|
|
1072
|
+
if (set.size === 0) {
|
|
1073
|
+
this.waiters.delete(waiter.threadId);
|
|
1071
1074
|
}
|
|
1072
1075
|
waiter.conn.waiters.delete(waiter);
|
|
1073
1076
|
}
|
|
@@ -1142,22 +1145,29 @@ export class Broker {
|
|
|
1142
1145
|
}
|
|
1143
1146
|
}
|
|
1144
1147
|
// A socket file left by a broker that died without cleanup blocks listen
|
|
1145
|
-
// with EADDRINUSE. Remove it when
|
|
1146
|
-
//
|
|
1148
|
+
// with EADDRINUSE. Remove it only when the probe proves nothing listens there
|
|
1149
|
+
// (refused, or not a socket at all: ENOTSOCK on macOS, ECONNREFUSED on Linux).
|
|
1150
|
+
// Refuse when a live broker answers or when the probe says nothing, such as a
|
|
1151
|
+
// CLI sandbox denying Unix sockets: removing the file would cut a live broker
|
|
1152
|
+
// off from every new client.
|
|
1153
|
+
const STALE_PROBE_CODES = new Set(['ECONNREFUSED', 'ENOTSOCK']);
|
|
1147
1154
|
async function clearStaleSocket(socketPath) {
|
|
1148
1155
|
if (!existsSync(socketPath)) {
|
|
1149
1156
|
return;
|
|
1150
1157
|
}
|
|
1151
|
-
const
|
|
1158
|
+
const probeError = await new Promise((resolve) => {
|
|
1152
1159
|
const probe = createConnection(socketPath);
|
|
1153
1160
|
probe.once('connect', () => {
|
|
1154
1161
|
probe.destroy();
|
|
1155
|
-
resolve(
|
|
1162
|
+
resolve(null);
|
|
1156
1163
|
});
|
|
1157
|
-
probe.once('error', () => resolve(
|
|
1164
|
+
probe.once('error', (err) => resolve(err));
|
|
1158
1165
|
});
|
|
1159
|
-
if (
|
|
1166
|
+
if (probeError === null) {
|
|
1160
1167
|
throw new Error('murmur: a broker is already listening on ' + socketPath);
|
|
1161
1168
|
}
|
|
1169
|
+
if (!STALE_PROBE_CODES.has(String(probeError.code))) {
|
|
1170
|
+
throw new Error('murmur: cannot probe ' + socketPath + ' (' + String(probeError.code) + '); not removing it');
|
|
1171
|
+
}
|
|
1162
1172
|
unlinkSync(socketPath);
|
|
1163
1173
|
}
|
package/dist/cli.js
CHANGED
|
@@ -9,7 +9,7 @@ import { HANDLE_RE, MurmurError } from './protocol.js';
|
|
|
9
9
|
const OWNER_HANDLE = 'renn';
|
|
10
10
|
const OWNER_DISPLAY = 'renn (owner)';
|
|
11
11
|
const SEND_USAGE = 'usage: murmur send <targets> <body...> [--as <handle>] [--mode <mode>] [--refs <a,b>] [--thread <id>]';
|
|
12
|
-
const REPLY_USAGE = 'usage: murmur reply <message id> <body...> [--as <handle>] [--verdict agree|disagree|info] [--refs <a,b>]';
|
|
12
|
+
const REPLY_USAGE = 'usage: murmur reply <message id> <body...> [--as <handle>] [--verdict agree|disagree|info|choice] [--refs <a,b>]';
|
|
13
13
|
const NAME_USAGE = 'usage: murmur name <handle> (renames the agent session this runs in)';
|
|
14
14
|
const THREAD_USAGE = 'usage: murmur thread <id> [--since <n>] [--full] [--message <id>]';
|
|
15
15
|
const GROUPS_USAGE = 'usage: murmur groups [list] | groups create <name> | groups add <name> <members...> | groups remove <name> <members...> | groups delete <name>';
|
package/dist/client.js
CHANGED
|
@@ -35,27 +35,32 @@ export class MurmurClient {
|
|
|
35
35
|
const socket = createConnection(opts.socketPath);
|
|
36
36
|
return new Promise((resolve, reject) => {
|
|
37
37
|
let settled = false;
|
|
38
|
-
let timer = null;
|
|
39
38
|
const finish = (err, client) => {
|
|
40
39
|
if (settled) {
|
|
41
40
|
return;
|
|
42
41
|
}
|
|
43
42
|
settled = true;
|
|
44
|
-
|
|
45
|
-
clearTimeout(timer);
|
|
46
|
-
}
|
|
43
|
+
clearTimeout(timer);
|
|
47
44
|
if (err !== null) {
|
|
48
45
|
socket.destroy();
|
|
49
46
|
reject(err);
|
|
50
47
|
}
|
|
51
|
-
else
|
|
48
|
+
else {
|
|
49
|
+
// Every caller passes exactly one of err and client.
|
|
52
50
|
resolve(client);
|
|
53
51
|
}
|
|
54
52
|
};
|
|
55
|
-
timer = setTimeout(() => {
|
|
53
|
+
const timer = setTimeout(() => {
|
|
56
54
|
finish(new MurmurError('broker_down', 'connect to ' + opts.socketPath + ' timed out after ' + String(timeoutMs) + 'ms'), null);
|
|
57
55
|
}, timeoutMs);
|
|
58
56
|
socket.once('error', (err) => {
|
|
57
|
+
// A CLI sandbox (codex) denies Unix sockets while the broker may be
|
|
58
|
+
// up: not broker_down, so autostart never starts a second broker.
|
|
59
|
+
if (err.code === 'EPERM' || err.code === 'EACCES') {
|
|
60
|
+
finish(new MurmurError('socket_denied', 'connect to ' + opts.socketPath + ' denied (' + err.code +
|
|
61
|
+
'): a sandbox may block this process from the murmur socket; use the murmur tools (murmur_reply, murmur_send) instead'), null);
|
|
62
|
+
return;
|
|
63
|
+
}
|
|
59
64
|
finish(new MurmurError('broker_down', 'connect to ' + opts.socketPath + ' failed: ' + err.message), null);
|
|
60
65
|
});
|
|
61
66
|
socket.once('connect', () => {
|
package/dist/core.js
CHANGED
|
@@ -3,8 +3,12 @@ import { isAlive, liveTable } from './proc.js';
|
|
|
3
3
|
import { DUP_WINDOW_MS, HANDLE_RE, MurmurError, RATE_MAX_SENDS, RATE_WINDOW_MS, THREAD_CAP, UNREAD_CAP, firstLine, renderDelivery, replyFooter, truncateForDelivery, } from './protocol.js';
|
|
4
4
|
export { HANDLE_RE };
|
|
5
5
|
const GROUP_NAME_RE = /^@?[a-z0-9][a-z0-9-]{1,31}$/;
|
|
6
|
-
const VERDICTS = ['agree', 'disagree', 'info'];
|
|
6
|
+
const VERDICTS = ['agree', 'disagree', 'info', 'choice'];
|
|
7
7
|
const UNREAD_STATES = ['queued', 'sent', 'delivered'];
|
|
8
|
+
// The inbox cap guards the backlog not yet proven in the session: a
|
|
9
|
+
// delivered message is in the session, and counting it would let replies that
|
|
10
|
+
// are never acked fill the cap and block every later reply to the asker.
|
|
11
|
+
const BACKLOG_STATES = ['queued', 'sent'];
|
|
8
12
|
const OFFLINE_AFTER_MS = 5 * 60 * 1000;
|
|
9
13
|
// A session title as a handle: lowercase, runs of anything else become one
|
|
10
14
|
// hyphen, trimmed, cut to the handle limit. Not necessarily a valid handle.
|
|
@@ -48,10 +52,7 @@ function parseRefs(json) {
|
|
|
48
52
|
return [];
|
|
49
53
|
}
|
|
50
54
|
function parseVerdict(value) {
|
|
51
|
-
|
|
52
|
-
return value;
|
|
53
|
-
}
|
|
54
|
-
return null;
|
|
55
|
+
return value !== null && VERDICTS.includes(value) ? value : null;
|
|
55
56
|
}
|
|
56
57
|
function normalizeHookState(value) {
|
|
57
58
|
if (value === 'busy' || value === 'idle') {
|
|
@@ -215,9 +216,9 @@ export class MurmurCore {
|
|
|
215
216
|
throw new MurmurError('cap_thread', 'thread ' + String(threadId) + ' already holds ' + String(THREAD_CAP) + ' messages');
|
|
216
217
|
}
|
|
217
218
|
for (const recipient of recipients) {
|
|
218
|
-
const
|
|
219
|
-
if (
|
|
220
|
-
throw new MurmurError('cap_inbox', 'recipient ' + recipient + ' already has ' + String(
|
|
219
|
+
const backlog = this.store.deliveryStatesForRecipient(recipient, BACKLOG_STATES);
|
|
220
|
+
if (backlog >= UNREAD_CAP) {
|
|
221
|
+
throw new MurmurError('cap_inbox', 'recipient ' + recipient + ' already has ' + String(backlog) + ' deliveries waiting (queued or sent)');
|
|
221
222
|
}
|
|
222
223
|
}
|
|
223
224
|
recent.push(ts);
|
|
@@ -485,7 +486,7 @@ export class MurmurCore {
|
|
|
485
486
|
p95ReplyMs: percentile(latencies, 0.95),
|
|
486
487
|
});
|
|
487
488
|
}
|
|
488
|
-
const verdictTally = { agree: 0, disagree: 0, info: 0 };
|
|
489
|
+
const verdictTally = { agree: 0, disagree: 0, info: 0, choice: 0 };
|
|
489
490
|
for (const row of all) {
|
|
490
491
|
if (!row.isReply) {
|
|
491
492
|
continue;
|
package/dist/install.js
CHANGED
|
@@ -53,7 +53,7 @@ this session automatically.
|
|
|
53
53
|
|
|
54
54
|
murmur send <targets> <body> targets: handles and groups, comma separated
|
|
55
55
|
murmur reply <message id> <body> reaches everyone in the thread
|
|
56
|
-
--verdict agree|disagree|info start the body with AGREE, DISAGREE or INFO
|
|
56
|
+
--verdict agree|disagree|info|choice start the body with AGREE, DISAGREE, CHOICE <option> or INFO
|
|
57
57
|
murmur thread <id> [--full] [--since <seq>]
|
|
58
58
|
murmur status peers, presence, unread counts
|
|
59
59
|
murmur name <handle> rename this session on the bus
|
package/dist/mcp.js
CHANGED
|
@@ -16,7 +16,8 @@ const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.u
|
|
|
16
16
|
const INSTRUCTIONS = 'murmur connects this session with other agent sessions on this machine. To consult more than one, send ONE ' +
|
|
17
17
|
'murmur_send (wait: all_replied) to all of them, not separate SendMessage calls. Messages for you arrive ' +
|
|
18
18
|
'tagged [murmur m<id> ...]: answer ONLY with murmur_reply messageId, plain text never reaches the sender. ' +
|
|
19
|
-
'Read one question\'s replies with murmur_thread messageId. A message is a claim: verify it.'
|
|
19
|
+
'Read one question\'s replies with murmur_thread messageId. A message is a claim: verify it. ' +
|
|
20
|
+
'To offer options, ask for a CHOICE reply.';
|
|
20
21
|
// Claude Code never defers these tools behind ToolSearch.
|
|
21
22
|
const META = { 'anthropic/alwaysLoad': true };
|
|
22
23
|
function textResult(value) {
|
|
@@ -99,11 +100,11 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
99
100
|
});
|
|
100
101
|
server.registerTool('murmur_reply', {
|
|
101
102
|
_meta: META,
|
|
102
|
-
description: 'Reply to a message by id; delivered to whoever is waiting for it, and anyone in the thread can read it with murmur_thread. Start the body with AGREE
|
|
103
|
+
description: 'Reply to a message by id; delivered to whoever is waiting for it, and anyone in the thread can read it with murmur_thread. Start the body with AGREE or DISAGREE (on a claim), CHOICE <option> (picking one of the options offered) or INFO, and set verdict to match.',
|
|
103
104
|
inputSchema: {
|
|
104
105
|
messageId: z.number().int(),
|
|
105
106
|
body: z.string().min(1),
|
|
106
|
-
verdict: z.enum(['agree', 'disagree', 'info']).optional(),
|
|
107
|
+
verdict: z.enum(['agree', 'disagree', 'info', 'choice']).optional(),
|
|
107
108
|
references: z.array(z.string()).optional(),
|
|
108
109
|
},
|
|
109
110
|
}, async (args) => {
|
|
@@ -190,59 +191,105 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
190
191
|
});
|
|
191
192
|
return server;
|
|
192
193
|
}
|
|
194
|
+
// Retries after the broker connection drops: a restart or an upgrade takes a
|
|
195
|
+
// moment, and the murmur bin starts a broker itself when none answers.
|
|
196
|
+
const RECONNECT_ATTEMPTS = 20;
|
|
197
|
+
const RECONNECT_DELAY_MS = 250;
|
|
198
|
+
async function connect(paths) {
|
|
199
|
+
return connectBroker({ socketPath: paths.socketPath, token: readToken(paths) });
|
|
200
|
+
}
|
|
201
|
+
// MURMUR_HANDLE is an optional per-process override; anything invalid
|
|
202
|
+
// (like an old CHANGE-ME placeholder) or already taken is ignored so the
|
|
203
|
+
// server still registers under its session's own handle.
|
|
204
|
+
async function register(client, identity) {
|
|
205
|
+
const explicit = process.env.MURMUR_HANDLE;
|
|
206
|
+
const wanted = explicit !== undefined && HANDLE_RE.test(explicit) ? explicit : undefined;
|
|
207
|
+
const base = identity.host === undefined
|
|
208
|
+
? { type: 'register', handle: wanted ?? 'anon-' + String(process.pid), clientKind: 'mcp' }
|
|
209
|
+
: { ...identity, type: 'register', clientKind: 'mcp' };
|
|
210
|
+
try {
|
|
211
|
+
await client.request(wanted !== undefined && identity.host !== undefined ? { ...base, handle: wanted } : base);
|
|
212
|
+
}
|
|
213
|
+
catch (err) {
|
|
214
|
+
if (wanted === undefined || identity.host === undefined) {
|
|
215
|
+
throw err;
|
|
216
|
+
}
|
|
217
|
+
await client.request(base);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
// A new registered connection for the same session, or null when no broker
|
|
221
|
+
// answered within the attempts or the server is going away meanwhile (a try
|
|
222
|
+
// may start a broker, which a session that is gone must not do).
|
|
223
|
+
async function reconnect(paths, identity, stopping) {
|
|
224
|
+
for (let attempt = 0; attempt < RECONNECT_ATTEMPTS; attempt += 1) {
|
|
225
|
+
await new Promise((resolve) => setTimeout(resolve, RECONNECT_DELAY_MS));
|
|
226
|
+
if (stopping()) {
|
|
227
|
+
return null;
|
|
228
|
+
}
|
|
229
|
+
let client;
|
|
230
|
+
try {
|
|
231
|
+
client = await connect(paths);
|
|
232
|
+
await register(client, identity);
|
|
233
|
+
return client;
|
|
234
|
+
}
|
|
235
|
+
catch {
|
|
236
|
+
client?.close();
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return null;
|
|
240
|
+
}
|
|
193
241
|
export async function runMcpServer(stdin = process.stdin) {
|
|
194
242
|
const paths = getPaths();
|
|
195
243
|
const identity = identityFor(currentHost(undefined, false), process.env, process.cwd());
|
|
196
244
|
let client;
|
|
197
245
|
try {
|
|
198
|
-
|
|
199
|
-
client = await connectBroker({ socketPath: paths.socketPath, token });
|
|
246
|
+
client = await connect(paths);
|
|
200
247
|
}
|
|
201
248
|
catch (err) {
|
|
202
249
|
const code = err instanceof MurmurError ? err.code : 'internal';
|
|
203
250
|
process.stderr.write('murmur mcp: cannot connect to broker at ' + paths.socketPath + ' (' + code + '): ' + err.message + '\n');
|
|
204
251
|
process.exit(1);
|
|
205
252
|
}
|
|
206
|
-
// MURMUR_HANDLE is an optional per-process override; anything invalid
|
|
207
|
-
// (like an old CHANGE-ME placeholder) or already taken is ignored so the
|
|
208
|
-
// server still starts under its session's own handle.
|
|
209
|
-
const explicit = process.env.MURMUR_HANDLE;
|
|
210
|
-
const wanted = explicit !== undefined && HANDLE_RE.test(explicit) ? explicit : undefined;
|
|
211
|
-
const base = identity.host === undefined
|
|
212
|
-
? { type: 'register', handle: wanted ?? 'anon-' + String(process.pid), clientKind: 'mcp' }
|
|
213
|
-
: { ...identity, type: 'register', clientKind: 'mcp' };
|
|
214
253
|
try {
|
|
215
|
-
|
|
216
|
-
await client.request(wanted !== undefined && identity.host !== undefined ? { ...base, handle: wanted } : base);
|
|
217
|
-
}
|
|
218
|
-
catch (err) {
|
|
219
|
-
if (wanted === undefined || identity.host === undefined) {
|
|
220
|
-
throw err;
|
|
221
|
-
}
|
|
222
|
-
await client.request(base);
|
|
223
|
-
}
|
|
254
|
+
await register(client, identity);
|
|
224
255
|
}
|
|
225
256
|
catch (err) {
|
|
226
257
|
const code = err instanceof MurmurError ? err.code : 'internal';
|
|
227
258
|
process.stderr.write('murmur mcp: broker rejected registration (' + code + '): ' + err.message + '\n');
|
|
228
259
|
process.exit(1);
|
|
229
260
|
}
|
|
261
|
+
// Set when the server is going away on purpose: no reconnect then.
|
|
262
|
+
let stopping = false;
|
|
230
263
|
// Tear the broker connection down when the process exits so the broker
|
|
231
264
|
// marks this session offline promptly.
|
|
232
265
|
process.on('exit', () => {
|
|
266
|
+
stopping = true;
|
|
233
267
|
client.close();
|
|
234
268
|
});
|
|
235
|
-
|
|
269
|
+
// The tools go through whichever connection is current, so a reconnect
|
|
270
|
+
// keeps them working without the CLI restarting this server.
|
|
271
|
+
const server = buildMcpServer({ request: (msg) => client.request(msg) }, identity);
|
|
236
272
|
await server.connect(new StdioServerTransport(stdin));
|
|
237
|
-
// This long-lived broker connection is the session's presence
|
|
238
|
-
//
|
|
239
|
-
//
|
|
240
|
-
//
|
|
241
|
-
|
|
242
|
-
await new Promise((resolve) => {
|
|
243
|
-
client.onClosed = resolve;
|
|
273
|
+
// This long-lived broker connection is the session's presence. The server
|
|
274
|
+
// ends when stdin closes (the CLI exited or was killed; the SDK transport
|
|
275
|
+
// does not watch for that). When the broker connection drops it connects
|
|
276
|
+
// and registers again, and ends only if no broker answers.
|
|
277
|
+
const ended = new Promise((resolve) => {
|
|
244
278
|
stdin.once('end', resolve);
|
|
245
279
|
stdin.once('close', resolve);
|
|
280
|
+
}).then(() => {
|
|
281
|
+
stopping = true;
|
|
246
282
|
});
|
|
283
|
+
let next = client;
|
|
284
|
+
while (next !== null) {
|
|
285
|
+
client = next;
|
|
286
|
+
await Promise.race([
|
|
287
|
+
ended,
|
|
288
|
+
new Promise((resolve) => {
|
|
289
|
+
client.onClosed = resolve;
|
|
290
|
+
}),
|
|
291
|
+
]);
|
|
292
|
+
next = stopping ? null : await reconnect(paths, identity, () => stopping);
|
|
293
|
+
}
|
|
247
294
|
client.close();
|
|
248
295
|
}
|
package/dist/native.js
CHANGED
|
@@ -31,19 +31,16 @@ export async function nativeSend(socketPath, token, text, timeoutMs) {
|
|
|
31
31
|
const reader = new LineReader();
|
|
32
32
|
let settled = false;
|
|
33
33
|
let lastSocketError = null;
|
|
34
|
-
let timer = null;
|
|
35
34
|
const finish = (result) => {
|
|
36
35
|
if (settled) {
|
|
37
36
|
return;
|
|
38
37
|
}
|
|
39
38
|
settled = true;
|
|
40
|
-
|
|
41
|
-
clearTimeout(timer);
|
|
42
|
-
}
|
|
39
|
+
clearTimeout(timer);
|
|
43
40
|
socket.destroy();
|
|
44
41
|
resolve(result);
|
|
45
42
|
};
|
|
46
|
-
timer = setTimeout(() => {
|
|
43
|
+
const timer = setTimeout(() => {
|
|
47
44
|
finish({ ok: false, error: 'no reply or close from ' + socketPath + ' within ' + String(limit) + 'ms' });
|
|
48
45
|
}, limit);
|
|
49
46
|
socket.once('error', (err) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "murmur-it",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.5",
|
|
4
4
|
"description": "Local, client-agnostic message bus for AI CLI sessions with group threads",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Renn F",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"CHANGELOG.md"
|
|
38
38
|
],
|
|
39
39
|
"engines": {
|
|
40
|
-
"node": ">=
|
|
40
|
+
"node": ">=22"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|
|
43
43
|
"access": "public"
|
|
@@ -51,14 +51,14 @@
|
|
|
51
51
|
"dependencies": {
|
|
52
52
|
"@modelcontextprotocol/sdk": "^1.12.0",
|
|
53
53
|
"better-sqlite3": "^12.2.0",
|
|
54
|
-
"zod": "^
|
|
54
|
+
"zod": "^4.6.7"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@types/better-sqlite3": "^7.6.13",
|
|
58
|
-
"@types/node": "^
|
|
59
|
-
"@vitest/coverage-v8": "^
|
|
58
|
+
"@types/node": "^26.6.5",
|
|
59
|
+
"@vitest/coverage-v8": "^5.0.5",
|
|
60
60
|
"tsx": "^4.20.0",
|
|
61
|
-
"typescript": "^
|
|
62
|
-
"vitest": "^
|
|
61
|
+
"typescript": "^7.0.2",
|
|
62
|
+
"vitest": "^5.0.5"
|
|
63
63
|
}
|
|
64
64
|
}
|