murmur-it 0.2.2 → 0.2.4
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 +44 -3
- package/README.md +69 -29
- package/adapters/hummin/murmur.ts +1 -1
- package/adapters/opencode/murmur.ts +1 -1
- package/dist/broker.js +69 -11
- package/dist/cli.js +15 -4
- package/dist/client.js +4 -6
- package/dist/core.js +46 -18
- package/dist/install.js +5 -3
- package/dist/mcp.js +32 -8
- package/dist/native.js +2 -5
- package/dist/protocol.js +2 -2
- package/package.json +7 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,8 +1,48 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All notable changes to murmur are documented here. The format follows
|
|
4
|
-
|
|
5
|
-
[
|
|
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
|
+
|
|
5
|
+
## [0.2.4] - 2026-10-21
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
|
|
9
|
+
- 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.
|
|
10
|
+
- 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.
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- 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`).
|
|
15
|
+
- 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.
|
|
16
|
+
- 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.
|
|
17
|
+
|
|
18
|
+
### Security
|
|
19
|
+
|
|
20
|
+
- 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.
|
|
21
|
+
|
|
22
|
+
## [0.2.3] - 2026-10-20
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- Murmur is a group chat: a message is posted once and everyone in the thread can read it, but nobody is woken for a message that is not for them. A reply is stored once and delivered (with a push, in the parent's mode) only to whoever is waiting for it: the author of the message it answers plus the session an owner message was typed in (`via`); a reply inside the replier's own thread goes to the parent's recipients. Other participants get no delivery row and no push and read the reply with `murmur_thread` / `murmur thread`. Measured reason: `make bench-consult` (haiku, three sessions) cost 546,811 tokens per consult for murmur against 265,771 for native `SendMessage`, because every reply woke every participant and the Implementer received each reply twice (once in the wait, once as a pushed turn).
|
|
27
|
+
- `murmur_wait` returns the text of the replies addressed to the waiting handle (`replies`: id, seq, sender, verdict, delivered body with the truncation pointer). A reply that arrives while its recipient has a wait open on that thread is not pushed; it stays queued, is handed over in the wait result (condition met or timeout) and marked delivered. A reply that arrives with no wait open is pushed as before.
|
|
28
|
+
- `murmur_thread` takes an optional `messageId` (CLI `murmur thread <id> --message <m>`): the result is only that message and the replies to it, with full delivered bodies; a message not in the thread is a `bad_request`. The footer of every delivered message now points at it (`replies to this: murmur_thread <t> messageId <m>`) instead of the whole thread, and the wait handover is limited to replies to the thread's latest ask.
|
|
29
|
+
- The MCP instructions, the `murmur_reply` and `murmur_wait` descriptions, the opencode and Hummin adapter descriptions and the docs describe this routing.
|
|
30
|
+
- Claude Code never defers murmur's tools: `murmur install claude` writes `"alwaysLoad": true` into `mcpServers.murmur` (idempotent; re-run it on an existing install) and the MCP server lists every tool with `_meta: { "anthropic/alwaysLoad": true }`. Measured reason: each deferred tool cost a ToolSearch call, and a Claude Code call re-reads the whole context (about 38k tokens on haiku).
|
|
31
|
+
- Teaching the reply: the footer on every delivered message and the MCP instructions say plainly that the answer goes through `murmur_reply` with that messageId and that plain text never reaches the sender.
|
|
32
|
+
- `murmur_send` takes optional `wait` (`all_replied` or `any_replied`) and `timeoutMs` (same default and cap as `murmur_wait`): it sends and waits on that thread in the same call and returns `{ sent, wait }` with states, verdicts and the replies' text. Asking is one tool call.
|
|
33
|
+
- `to` also accepts a session's display name (its CLI title, case-insensitive) or a name whose slug is a handle (`Peer A` resolves to `peer-a`). Handles and groups win; an ambiguous name is a `bad_request` listing the candidates.
|
|
34
|
+
- The `/murmur` command file for Claude Code and zcode sets `disable-model-invocation: true`: it is the owner's command, and a model that invoked it through the Skill tool sent nothing. Re-run `murmur install claude` / `zcode` to get it.
|
|
35
|
+
- `make bench-consult` counts a run as completed only when the Implementer's final answer holds both peers' verdicts and their answers really reached it, and reports API calls and ToolSearch calls per session. Result (haiku, 3 runs per setup, medians): plain native `SendMessage` completes 0 of 3 (268,272 tokens, 7 API calls), because its peers answer in plain text that never reaches the Implementer; native with the peers told to answer with `SendMessage` completes 3 of 3 (510,931 tokens, 13 API calls, 13.8 s); murmur completes 3 of 3 (362,879 tokens, 9 API calls, 10.1 s), 29 percent fewer tokens than the native setup that finishes.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- A reply held back for an open `murmur_wait` is now only one the wait hands over (a reply to the thread's latest ask); a reply to an older ask, or to a reply, is pushed as usual instead of staying queued with no path to its recipient. A wait remembers the replies held for it and hands them all over even if the thread's latest ask changed meanwhile. Replies held for a wait whose connection closes before it resolves are pushed at once. A delivery whose push is already in flight is never handed over a second time by a new wait or the hook pull.
|
|
40
|
+
- The live rig (`scripts/live/lib.mjs`) sets `MURMUR_AUTOSTART=0`, so a hook that outlives cleanup cannot respawn a broker and none survives a live run.
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- `make bench-consult` (`scripts/live/bench-consult.mjs`): three real Claude sessions per run, plain native `SendMessage`, native with the peers told to reply with `SendMessage`, and murmur, with tokens, API calls, copies received and wall time from the sessions' own transcripts; results in `docs/bench/consult.md` and `consult.json`.
|
|
45
|
+
- Docs and repository files: README hero, demo and linked CLIs; a Diataxis docs navigation (getting started, using murmur, consult, design, concepts, reference); `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `MAINTAINERS.md`, `CODEOWNERS`, issue forms, a pull request template, Dependabot, an OpenSSF Scorecard workflow, a docs CI workflow (markdownlint, typos, lychee) and SHA-pinned GitHub Actions.
|
|
6
46
|
|
|
7
47
|
## [0.2.2] - 2026-10-20
|
|
8
48
|
|
|
@@ -81,6 +121,7 @@ All notable changes to murmur are documented here. The format follows
|
|
|
81
121
|
- Limits: send rate, duplicate window, thread and inbox caps.
|
|
82
122
|
- 283 tests at 100 percent lines and branches, and an end-to-end rig that replayed the live 3-peer scenario.
|
|
83
123
|
|
|
124
|
+
[0.2.3]: https://github.com/rennf93/murmur/releases/tag/v0.2.3
|
|
84
125
|
[0.2.2]: https://github.com/rennf93/murmur/releases/tag/v0.2.2
|
|
85
126
|
[0.2.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1
|
|
86
127
|
[0.2.1-rc.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1-rc.1
|
package/README.md
CHANGED
|
@@ -1,35 +1,79 @@
|
|
|
1
|
-
<
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="https://raw.githubusercontent.com/rennf93/murmur/master/docs/assets/murmur-512.png" alt="murmur icon" width="160">
|
|
2
4
|
|
|
3
5
|
# murmur
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
A local message bus so AI CLI sessions talk in group threads.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
[](https://www.npmjs.com/package/murmur-it)
|
|
10
|
+
[](https://github.com/rennf93/murmur/actions/workflows/ci.yml)
|
|
11
|
+
[](https://github.com/rennf93/murmur/blob/master/LICENSE)
|
|
12
|
+
[](https://rennf93.github.io/murmur/)
|
|
13
|
+
[](https://scorecard.dev/viewer/?uri=github.com/rennf93/murmur)
|
|
8
14
|
|
|
9
|
-
Full documentation
|
|
15
|
+
[Full documentation](https://rennf93.github.io/murmur/) | [Changelog](https://github.com/rennf93/murmur/blob/master/CHANGELOG.md) | [Contributing](https://github.com/rennf93/murmur/blob/master/CONTRIBUTING.md) | [Security](https://github.com/rennf93/murmur/blob/master/SECURITY.md)
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
Murmur is a local message bus for AI CLI sessions that share one machine and one user account. One broker process owns a SQLite store and one Unix domain socket; every agent session joins as a named peer, and peers talk in threads. One send produces one message that fans out to any mix of handles and groups, so no session writes the same announcement twice and no session relays another's words by hand. A reply goes to whoever is waiting for it, and everyone in the thread can read it. Senders always see, per recipient, whether a message is still queued, was handed to the session, was proven to have reached it, or was answered.
|
|
20
|
+
|
|
21
|
+
It works with Claude Code, Codex, Gemini CLI, zcode, opencode and Hummin. Each joins through the deepest hook its CLI offers (see the [truth table](#delivery-truth-table)), and any process that can run a shell command can use the `murmur` CLI.
|
|
22
|
+
|
|
23
|
+

|
|
24
|
+
|
|
25
|
+
This is a CLI demo with simulated peers: `alice` and `bob` are registered by a hidden setup line and reply with `--as`, against an isolated broker. No agent CLI is involved. The tape is [`docs/assets/demo.tape`](https://github.com/rennf93/murmur/blob/master/docs/assets/demo.tape).
|
|
26
|
+
|
|
27
|
+
## Quickstart
|
|
12
28
|
|
|
13
|
-
Requires Node
|
|
29
|
+
Requires Node 22 or newer.
|
|
14
30
|
|
|
15
31
|
```
|
|
16
|
-
npm install -g murmur-it
|
|
17
|
-
murmur init
|
|
18
|
-
murmur install claude
|
|
32
|
+
npm install -g murmur-it # the package is murmur-it; the command it installs is murmur
|
|
33
|
+
murmur init # ~/.murmur (0700), token (0600), murmur.db, owner peer
|
|
34
|
+
murmur install claude # or: codex | gemini | zcode | opencode | hummin
|
|
19
35
|
```
|
|
20
36
|
|
|
21
|
-
|
|
37
|
+
Start two sessions, then from inside one of them send to both with a single message (handles are `<cli>-<folder>`; `murmur status` lists them):
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
/murmur claude-api,codex-web Which of you owns the migration?
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Each session receives the message, and each reply goes to whoever is waiting for it. Everyone in the thread can read it with `murmur thread <id>`. [Getting started](https://rennf93.github.io/murmur/getting-started/) has the full walk-through.
|
|
44
|
+
|
|
45
|
+
## Why
|
|
46
|
+
|
|
47
|
+
The bus removes two costs and must never remove a third thing. The costs: duplicated composition, where every member of a group reformats the same fact, and sender-side relaying, where one session carries another's words to a third and garbles them. One message fans out; replies go to whoever is waiting and stay readable by the whole thread; the broker owns storage and delivery. Delivery modes are the token dial.
|
|
48
|
+
|
|
49
|
+
The third thing is independent verification: a message is a claim, not evidence. Peers verify against the artifacts themselves, which is why messages carry `references`, and why every session is told so by the MCP server's instructions.
|
|
50
|
+
|
|
51
|
+
Measured with `make bench-consult`: three real Claude Code sessions on haiku, the Implementer asked to consult Peer A and Peer B and report both answers, 3 runs per setup, medians, 2026-10-20.
|
|
52
|
+
|
|
53
|
+
| Setup | Finished | Tokens, all sessions | API calls | Wall time |
|
|
54
|
+
| --- | --- | --- | --- | --- |
|
|
55
|
+
| Native `SendMessage` | 0 of 3 (peers answer in plain text, nothing comes back) | 268,272 | 7 | 5.7 s |
|
|
56
|
+
| Native, peers told to reply with `SendMessage` | 3 of 3 | 510,931 | 13 | 13.8 s |
|
|
57
|
+
| murmur | 3 of 3 | 362,879 | 9 | 10.1 s |
|
|
58
|
+
|
|
59
|
+
Against the native setup that finishes, murmur used 29 percent fewer tokens and 4 fewer API calls. Each call costs about 38k tokens there, mostly Claude Code re-reading its own context, so the saving comes from fewer calls: one send reaches both peers, the tools are loaded up front, and the replies come back to the asker, nobody else is woken.
|
|
60
|
+
|
|
61
|
+
Method and numbers: [consult benchmark](https://rennf93.github.io/murmur/bench/consult/).
|
|
62
|
+
|
|
63
|
+
## Install
|
|
64
|
+
|
|
65
|
+
From source instead of npm: `npm install && npm run build && npm link` in a clone (puts the same `murmur` on PATH; every hook, MCP entry and command runs plain `murmur`).
|
|
22
66
|
|
|
23
67
|
The broker starts on demand: the first hook, MCP server or CLI command that finds it down starts one in the background (`murmur serve` runs it in the foreground; `murmur serve --daemon` detaches). `MURMUR_HOME` relocates the home for every component.
|
|
24
68
|
|
|
25
|
-
What each installer writes (idempotent merges; every touched file gets a one-time `.bak-murmur` copy first):
|
|
69
|
+
What each installer writes (idempotent merges; every touched file gets a one-time `.bak-murmur` copy first; install refuses to touch a config file that is not valid JSON):
|
|
26
70
|
|
|
27
71
|
| CLI | Files | Notes |
|
|
28
72
|
| --- | --- | --- |
|
|
29
73
|
| claude | `~/.claude/settings.json` hooks (SessionStart, UserPromptSubmit, Stop, SessionEnd), `mcpServers.murmur` in `~/.claude.json`, `~/.claude/commands/murmur.md` | Removes the old `CHANGE-ME-per-session` handle placeholder. |
|
|
30
74
|
| codex | `~/.codex/hooks.json` (SessionStart, UserPromptSubmit, Stop, SessionEnd), `[mcp_servers.murmur]` in `~/.codex/config.toml`, `~/.codex/prompts/murmur.md` | Codex asks you to trust new hooks once: open `/hooks`. The command is `/prompts:murmur`. |
|
|
31
75
|
| gemini | `~/.gemini/settings.json` hooks (SessionStart, BeforeAgent, AfterAgent, SessionEnd) and `mcpServers.murmur`, `~/.gemini/commands/murmur.toml` | |
|
|
32
|
-
|
|
|
76
|
+
| zcode | `~/.zcode/cli/config.json` (`hooks.enabled`, SessionStart, UserPromptSubmit, Stop; `mcp.servers.murmur`), `~/.zcode/commands/murmur.md`, `~/.zcode/skills/murmur/SKILL.md` | zcode has no SessionEnd hook. |
|
|
33
77
|
| opencode | `~/.config/opencode/plugins/murmur.ts`, `~/.config/opencode/commands/murmur.md` | The plugin is the whole integration (tools, push, presence). |
|
|
34
78
|
| hummin | `~/.hummin/agent/extensions/murmur.ts` | The extension is the whole integration, including a model-free `/murmur`. |
|
|
35
79
|
|
|
@@ -50,29 +94,29 @@ Delivery states, per recipient: `queued` (stored, nothing left the broker), `sen
|
|
|
50
94
|
|
|
51
95
|
| CLI | Live push into a running session | Waiting messages also arrive | Evidence for `delivered` |
|
|
52
96
|
| --- | --- | --- | --- |
|
|
53
|
-
| Claude Code | Native messaging socket (`CLAUDE_CODE_MESSAGING_SOCKET`): the session gets the message as a peer turn; an idle session starts working on it | At SessionStart, each prompt, and at turn end (Stop continues the turn) | The message tag found in the receiver's own transcript |
|
|
54
|
-
| Hummin | Extension calls `sendUserMessage` (follow-up when idle, steer mid-turn) | When the extension (re)connects | The extension confirms its session accepted it; the tag in the session file too |
|
|
55
|
-
| opencode | Plugin posts the message into the session with `promptAsync` | When the plugin (re)connects | The plugin confirms the post succeeded |
|
|
56
|
-
| Codex | `codex queue --thread <id>`; a running window takes it as a user turn | At SessionStart, each prompt, and at turn end (Stop continues the turn) | The tag in the receiver's rollout transcript |
|
|
57
|
-
| 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 |
|
|
58
|
-
|
|
|
97
|
+
| [Claude Code](https://claude.com/product/claude-code) | Native messaging socket (`CLAUDE_CODE_MESSAGING_SOCKET`): the session gets the message as a peer turn; an idle session starts working on it | At SessionStart, each prompt, and at turn end (Stop continues the turn) | The message tag found in the receiver's own transcript |
|
|
98
|
+
| [Hummin](https://github.com/rennf93/hummin) | Extension calls `sendUserMessage` (follow-up when idle, steer mid-turn) | When the extension (re)connects | The extension confirms its session accepted it; the tag in the session file too |
|
|
99
|
+
| [opencode](https://github.com/anomalyco/opencode) | Plugin posts the message into the session with `promptAsync` | When the plugin (re)connects | The plugin confirms the post succeeded |
|
|
100
|
+
| [Codex](https://github.com/openai/codex) | `codex queue --thread <id>`; a running window takes it as a user turn | At SessionStart, each prompt, and at turn end (Stop continues the turn) | The tag in the receiver's rollout transcript |
|
|
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
|
+
| [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) |
|
|
59
103
|
|
|
60
|
-
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.
|
|
61
105
|
|
|
62
106
|
What a session sees for every message, on every path:
|
|
63
107
|
|
|
64
108
|
```
|
|
65
109
|
[murmur m42 t7 s0 from ledger-3 to archify-2, prs-5]
|
|
66
110
|
<body, cut at 4000 characters with a pointer to the full text>
|
|
67
|
-
(
|
|
111
|
+
(answer with murmur_reply messageId 42, plain text never reaches the sender; from a shell: murmur reply 42 <text>; its replies: murmur_thread 7 messageId 42)
|
|
68
112
|
```
|
|
69
113
|
|
|
70
114
|
## Threads, groups, verdicts
|
|
71
115
|
|
|
72
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.
|
|
73
|
-
-
|
|
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.
|
|
74
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`.
|
|
75
|
-
- Verdicts: `agree`, `disagree`, `info`, with the body starting `AGREE`, `DISAGREE` or `INFO`. `murmur_wait` returns, for the thread's latest ask, each recipient's state, verdict and reply latency plus their historical p50 and p95, either when everyone (or anyone) replied or at the timeout (`timeoutMs: 0` returns now).
|
|
119
|
+
- Verdicts: `agree`, `disagree`, `info`, with the body starting `AGREE`, `DISAGREE` or `INFO`. `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).
|
|
76
120
|
- `references` carries pointers (paths, commits, URLs) so artifacts stay in their repos.
|
|
77
121
|
- Groups: create, list, add, remove, delete. Deleting a group never touches sessions, threads or history.
|
|
78
122
|
|
|
@@ -85,16 +129,12 @@ The human surface, as the owner:
|
|
|
85
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.
|
|
86
130
|
- `murmur send <targets> <body...> [--mode push|notify|silent] [--refs a,b] [--thread <id>] [--as <handle>]`
|
|
87
131
|
- `murmur reply <id> <body...> [--verdict agree|disagree|info] [--refs a,b] [--as <handle>]`
|
|
88
|
-
- `murmur status`, `murmur thread <id> [--since <seq>] [--full]`, `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)
|
|
89
|
-
|
|
90
|
-
## Doctrine
|
|
91
|
-
|
|
92
|
-
The bus removes two costs and must never remove a third thing. The costs: duplicated composition, where every member of a group reformats the same fact, and sender-side relaying, where one session carries another's words to a third and garbles them. One message fans out; replies reach the whole thread; the broker owns storage and delivery. Delivery modes are the token dial. The third thing is independent verification: a message is a claim, not evidence. Peers verify against the artifacts themselves, which is why messages carry `references`, and why every session is told so by the MCP server's instructions.
|
|
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)
|
|
93
133
|
|
|
94
134
|
## Limits
|
|
95
135
|
|
|
96
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.
|
|
97
|
-
- 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.
|
|
98
138
|
- `murmur_wait`: default 120 s, at most 300 s.
|
|
99
139
|
- Hooks: 10 s hard deadline, up to 10 messages per pull, exit 0 on every failure path.
|
|
100
140
|
- Transcript proof polls for 120 s after a push, then re-checks at that session's next hook event.
|
|
@@ -115,7 +155,7 @@ The bus removes two costs and must never remove a third thing. The costs: duplic
|
|
|
115
155
|
|
|
116
156
|
| Check | What it proves | Last result (2026-10-20) |
|
|
117
157
|
| --- | --- | --- |
|
|
118
|
-
| `claude` | Two sessions announce with native transports; one message to both goes sent, delivered (tag in each transcript), replied; each reply
|
|
158
|
+
| `claude` | Two sessions announce with native transports; one message to both goes sent, delivered (tag in each transcript), replied; each reply reaches the owner who asked and not the other session; `/murmur` stores `$(...)`, backticks, quotes, `!` and `$HOME` verbatim | PASS, haiku, replies in about 3.6 s |
|
|
119
159
|
| `codex` | The session announces with its thread id; `codex queue` reaches the running window; transcript proof; reply through the MCP tool | PASS, gpt-5.6-luna, 6.2 s |
|
|
120
160
|
| `hummin` | The extension injects, acks delivered, carries the reply; the model-free `/murmur` | PASS, zai/glm-5.3-flash, 6.0 s |
|
|
121
161
|
| `opencode` | The plugin announces, injects with `promptAsync`, acks delivered, carries the reply | PASS, opencode 1.19.3, opencode/glm-5.3-flash-free, reply in 5.2 s (the readiness check can take up to 60 s on the first start after an upgrade) |
|
|
@@ -363,7 +363,7 @@ 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;
|
|
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.",
|
|
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" }),
|
|
@@ -249,7 +249,7 @@ 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;
|
|
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.',
|
|
253
253
|
args: {
|
|
254
254
|
messageId: s.number(),
|
|
255
255
|
body: s.string(),
|
package/dist/broker.js
CHANGED
|
@@ -130,6 +130,8 @@ export class Broker {
|
|
|
130
130
|
notifyQueue = new Map();
|
|
131
131
|
// Thread id to waiters registered against that thread.
|
|
132
132
|
waiters = new Map();
|
|
133
|
+
// Deliveries a push is sending right now (messageId:recipient): no other path hands them over.
|
|
134
|
+
inFlight = new Set();
|
|
133
135
|
stopped = false;
|
|
134
136
|
stopPromise = null;
|
|
135
137
|
constructor(opts, server) {
|
|
@@ -271,6 +273,7 @@ export class Broker {
|
|
|
271
273
|
}
|
|
272
274
|
onSocketClose(conn) {
|
|
273
275
|
this.conns.delete(conn);
|
|
276
|
+
const unresolved = conn.waiters.size > 0;
|
|
274
277
|
for (const waiter of [...conn.waiters]) {
|
|
275
278
|
clearTimeout(waiter.timer);
|
|
276
279
|
this.removeWaiter(waiter);
|
|
@@ -278,6 +281,10 @@ export class Broker {
|
|
|
278
281
|
if (conn.handle !== null && this.presence.get(conn.handle) === conn) {
|
|
279
282
|
this.presence.delete(conn.handle);
|
|
280
283
|
}
|
|
284
|
+
// Replies held for the closed wait have no result to ride on: push them now.
|
|
285
|
+
if (unresolved && conn.handle !== null && !this.stopped) {
|
|
286
|
+
void this.pushQueued(conn.handle).catch(() => { });
|
|
287
|
+
}
|
|
281
288
|
// Stamp nothing on close; only register refreshes last_seen_at. Only a
|
|
282
289
|
// long-lived connection going away means the peer went away.
|
|
283
290
|
if (conn.handle !== null && conn.live && !this.stopped) {
|
|
@@ -671,7 +678,8 @@ export class Broker {
|
|
|
671
678
|
handleThread(rec) {
|
|
672
679
|
const threadId = reqNumber(rec, 'threadId');
|
|
673
680
|
const sinceSeq = reqNumberOrNull(rec, 'sinceSeq');
|
|
674
|
-
|
|
681
|
+
const messageId = rec.messageId === undefined ? undefined : reqNumber(rec, 'messageId');
|
|
682
|
+
return this.core.threadView(threadId, sinceSeq, reqBool(rec, 'full'), messageId);
|
|
675
683
|
}
|
|
676
684
|
handleCollect(rec) {
|
|
677
685
|
const threadId = reqNumber(rec, 'threadId');
|
|
@@ -711,7 +719,7 @@ export class Broker {
|
|
|
711
719
|
}
|
|
712
720
|
// Everything the pull hands out was queued, so each one tells its
|
|
713
721
|
// sender it finally arrived.
|
|
714
|
-
const result = this.core.pendingPush(handle, limit);
|
|
722
|
+
const result = this.core.pendingPush(handle, limit, (id) => this.inFlight.has(String(id) + ':' + handle));
|
|
715
723
|
for (const message of result.messages) {
|
|
716
724
|
this.enqueueNotification(message.sender, {
|
|
717
725
|
kind: 'queued_delivered',
|
|
@@ -735,7 +743,7 @@ export class Broker {
|
|
|
735
743
|
if (this.stopped) {
|
|
736
744
|
return;
|
|
737
745
|
}
|
|
738
|
-
if (target.kind === 'queued') {
|
|
746
|
+
if (target.kind === 'queued' || this.heldForWait(target.message, target.recipient)) {
|
|
739
747
|
continue;
|
|
740
748
|
}
|
|
741
749
|
await this.pushOne(target.message.id, target.message.threadId, target.recipient, target.text, {
|
|
@@ -746,6 +754,22 @@ export class Broker {
|
|
|
746
754
|
});
|
|
747
755
|
}
|
|
748
756
|
}
|
|
757
|
+
// A reply answering the thread's latest ask, whose recipient has a
|
|
758
|
+
// murmur_wait open on that thread, stays queued; the wait result carries it
|
|
759
|
+
// (takeReplies applies the same rule). Any other reply is pushed as normal.
|
|
760
|
+
heldForWait(message, recipient) {
|
|
761
|
+
if (!message.isReply || message.inReplyTo === null || this.store.latestAsk(message.threadId)?.id !== message.inReplyTo) {
|
|
762
|
+
return false;
|
|
763
|
+
}
|
|
764
|
+
let held = false;
|
|
765
|
+
for (const w of this.waiters.get(message.threadId) ?? []) {
|
|
766
|
+
if (w.conn.handle === recipient) {
|
|
767
|
+
w.held.add(message.id);
|
|
768
|
+
held = true;
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
return held;
|
|
772
|
+
}
|
|
749
773
|
async pushOne(messageId, threadId, recipient, text, payload) {
|
|
750
774
|
const listener = this.presence.get(recipient);
|
|
751
775
|
if (listener !== undefined && listener.listening && !listener.socket.destroyed) {
|
|
@@ -754,6 +778,16 @@ export class Broker {
|
|
|
754
778
|
this.markSent(messageId, threadId, recipient);
|
|
755
779
|
return;
|
|
756
780
|
}
|
|
781
|
+
const key = String(messageId) + ':' + recipient;
|
|
782
|
+
this.inFlight.add(key);
|
|
783
|
+
try {
|
|
784
|
+
await this.pushVia(messageId, threadId, recipient, text);
|
|
785
|
+
}
|
|
786
|
+
finally {
|
|
787
|
+
this.inFlight.delete(key);
|
|
788
|
+
}
|
|
789
|
+
}
|
|
790
|
+
async pushVia(messageId, threadId, recipient, text) {
|
|
757
791
|
const session = this.liveSessionOf(recipient);
|
|
758
792
|
const transcript = session?.transcriptPath ?? null;
|
|
759
793
|
const offset = transcript === null ? 0 : ProofWatcher.offsetOf(transcript);
|
|
@@ -783,6 +817,9 @@ export class Broker {
|
|
|
783
817
|
async pushQueued(handle) {
|
|
784
818
|
const waiting = this.store.pendingPushFor(handle, 50).reverse();
|
|
785
819
|
for (const { message } of waiting) {
|
|
820
|
+
if (this.heldForWait(message, handle)) {
|
|
821
|
+
continue;
|
|
822
|
+
}
|
|
786
823
|
const recipients = this.store.getDeliveries(message.id).map((d) => d.recipient);
|
|
787
824
|
const full = fullOf(message);
|
|
788
825
|
const text = renderDelivery(full, message.deliveredBody, recipients);
|
|
@@ -807,14 +844,14 @@ export class Broker {
|
|
|
807
844
|
}
|
|
808
845
|
// queued or sent to delivered, with the queued_delivered notice to the
|
|
809
846
|
// sender when the message had been waiting. False when not applicable.
|
|
810
|
-
markDeliveredHop(messageId, recipient) {
|
|
847
|
+
markDeliveredHop(messageId, recipient, notifySender = true) {
|
|
811
848
|
const message = this.store.messageById(messageId);
|
|
812
849
|
const delivery = this.store.getDeliveries(messageId).find((d) => d.recipient === recipient);
|
|
813
850
|
if (message === null || delivery === undefined || (delivery.state !== 'queued' && delivery.state !== 'sent')) {
|
|
814
851
|
return false;
|
|
815
852
|
}
|
|
816
853
|
this.store.markDelivered(messageId, recipient, Date.now());
|
|
817
|
-
if (delivery.state === 'queued') {
|
|
854
|
+
if (delivery.state === 'queued' && notifySender) {
|
|
818
855
|
this.enqueueNotification(message.sender, {
|
|
819
856
|
kind: 'queued_delivered',
|
|
820
857
|
threadId: message.threadId,
|
|
@@ -915,6 +952,7 @@ export class Broker {
|
|
|
915
952
|
conditionMet: true,
|
|
916
953
|
timedOut: false,
|
|
917
954
|
matrix: this.matrixFor(threadId),
|
|
955
|
+
replies: this.takeReplies(threadId, conn.handle),
|
|
918
956
|
});
|
|
919
957
|
return;
|
|
920
958
|
}
|
|
@@ -923,6 +961,7 @@ export class Broker {
|
|
|
923
961
|
id,
|
|
924
962
|
threadId,
|
|
925
963
|
until,
|
|
964
|
+
held: new Set(),
|
|
926
965
|
timer: setTimeout(() => this.resolveTimedOut(waiter), timeoutMs),
|
|
927
966
|
};
|
|
928
967
|
conn.waiters.add(waiter);
|
|
@@ -950,6 +989,22 @@ export class Broker {
|
|
|
950
989
|
}
|
|
951
990
|
return deliveries.every((d) => d.state === 'replied');
|
|
952
991
|
}
|
|
992
|
+
// The replies still queued for this handle in the thread, handed over in the
|
|
993
|
+
// wait result and marked delivered (the wait result is the receiving-side proof).
|
|
994
|
+
takeReplies(threadId, handle, held) {
|
|
995
|
+
const replies = [];
|
|
996
|
+
const ask = this.store.latestAsk(threadId);
|
|
997
|
+
for (const row of this.store.threadMessages(threadId, null)) {
|
|
998
|
+
const delivery = this.store.getDeliveries(row.id).find((d) => d.recipient === handle);
|
|
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
|
+
// 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);
|
|
1003
|
+
replies.push({ id: row.id, seq: row.seq, sender: row.sender, verdict: row.verdict, body: row.deliveredBody });
|
|
1004
|
+
}
|
|
1005
|
+
}
|
|
1006
|
+
return replies;
|
|
1007
|
+
}
|
|
953
1008
|
// The collect matrix for a WaitResult. A thread without messages or without
|
|
954
1009
|
// an ask collects nothing, which degrades to an empty matrix.
|
|
955
1010
|
matrixFor(threadId) {
|
|
@@ -976,7 +1031,8 @@ export class Broker {
|
|
|
976
1031
|
if (this.stopped) {
|
|
977
1032
|
return;
|
|
978
1033
|
}
|
|
979
|
-
|
|
1034
|
+
// A handover below re-enters checkWaiters and may already have answered this waiter.
|
|
1035
|
+
if (!set.has(waiter) || !this.conditionHolds(threadId, waiter.until)) {
|
|
980
1036
|
continue;
|
|
981
1037
|
}
|
|
982
1038
|
this.removeWaiter(waiter);
|
|
@@ -986,6 +1042,7 @@ export class Broker {
|
|
|
986
1042
|
conditionMet: true,
|
|
987
1043
|
timedOut: false,
|
|
988
1044
|
matrix: this.matrixFor(threadId),
|
|
1045
|
+
replies: this.takeReplies(threadId, waiter.conn.handle, waiter.held),
|
|
989
1046
|
});
|
|
990
1047
|
}
|
|
991
1048
|
}
|
|
@@ -1000,19 +1057,20 @@ export class Broker {
|
|
|
1000
1057
|
conditionMet: false,
|
|
1001
1058
|
timedOut: true,
|
|
1002
1059
|
matrix: this.matrixFor(waiter.threadId),
|
|
1060
|
+
replies: this.takeReplies(waiter.threadId, waiter.conn.handle, waiter.held),
|
|
1003
1061
|
});
|
|
1004
1062
|
}
|
|
1005
1063
|
catch {
|
|
1006
1064
|
// Never let a timer callback crash the process.
|
|
1007
1065
|
}
|
|
1008
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.
|
|
1009
1069
|
removeWaiter(waiter) {
|
|
1010
1070
|
const set = this.waiters.get(waiter.threadId);
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
this.waiters.delete(waiter.threadId);
|
|
1015
|
-
}
|
|
1071
|
+
set.delete(waiter);
|
|
1072
|
+
if (set.size === 0) {
|
|
1073
|
+
this.waiters.delete(waiter.threadId);
|
|
1016
1074
|
}
|
|
1017
1075
|
waiter.conn.waiters.delete(waiter);
|
|
1018
1076
|
}
|
package/dist/cli.js
CHANGED
|
@@ -11,7 +11,7 @@ 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
12
|
const REPLY_USAGE = 'usage: murmur reply <message id> <body...> [--as <handle>] [--verdict agree|disagree|info] [--refs <a,b>]';
|
|
13
13
|
const NAME_USAGE = 'usage: murmur name <handle> (renames the agent session this runs in)';
|
|
14
|
-
const THREAD_USAGE = 'usage: murmur thread <id> [--since <n>] [--full]';
|
|
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>';
|
|
16
16
|
const SLASH_USAGE = '/murmur <group | handle[,more]> <message> (sent as renn, via the session you type it in; run bare like this for peers and groups)';
|
|
17
17
|
export async function runCli(argv, io) {
|
|
@@ -95,7 +95,7 @@ function printUsage(err) {
|
|
|
95
95
|
' slash [args...] the /murmur backing, sent as the owner via your session; bare prints peers and groups',
|
|
96
96
|
' prune remove peers with no session, message, group or connection',
|
|
97
97
|
' status list peers with presence and unread counts',
|
|
98
|
-
' thread <id> [--since <n>] [--full]',
|
|
98
|
+
' thread <id> [--since <n>] [--full] [--message <id>]',
|
|
99
99
|
' groups [list] | groups create <name> | groups add <name> <members...>',
|
|
100
100
|
' | groups remove <name> <members...> | groups delete <name>',
|
|
101
101
|
' install <' + INSTALL_CLIENTS.join('|') + '>',
|
|
@@ -430,6 +430,7 @@ async function cmdPrune(out) {
|
|
|
430
430
|
async function cmdThread(args, out, err) {
|
|
431
431
|
let full = false;
|
|
432
432
|
let sinceSeq = null;
|
|
433
|
+
let messageId;
|
|
433
434
|
const positionals = [];
|
|
434
435
|
for (let i = 0; i < args.length; i += 1) {
|
|
435
436
|
const arg = args[i];
|
|
@@ -440,6 +441,16 @@ async function cmdThread(args, out, err) {
|
|
|
440
441
|
full = true;
|
|
441
442
|
continue;
|
|
442
443
|
}
|
|
444
|
+
if (arg === '--message') {
|
|
445
|
+
const parsed = Number(args[i + 1]);
|
|
446
|
+
if (args[i + 1] === undefined || !Number.isInteger(parsed) || parsed < 0) {
|
|
447
|
+
err('murmur thread: --message needs a non-negative integer\n' + THREAD_USAGE + '\n');
|
|
448
|
+
return 1;
|
|
449
|
+
}
|
|
450
|
+
i += 1;
|
|
451
|
+
messageId = parsed;
|
|
452
|
+
continue;
|
|
453
|
+
}
|
|
443
454
|
if (arg === '--since') {
|
|
444
455
|
const value = args[i + 1];
|
|
445
456
|
if (value === undefined) {
|
|
@@ -469,10 +480,10 @@ async function cmdThread(args, out, err) {
|
|
|
469
480
|
}
|
|
470
481
|
const client = await connectCli();
|
|
471
482
|
try {
|
|
472
|
-
const msg = { type: 'thread', threadId, sinceSeq, full };
|
|
483
|
+
const msg = { type: 'thread', threadId, sinceSeq, full, ...(messageId !== undefined ? { messageId } : {}) };
|
|
473
484
|
const result = await client.request(msg);
|
|
474
485
|
for (const message of result.messages) {
|
|
475
|
-
const text = full ? message.body : message.firstLine;
|
|
486
|
+
const text = full || messageId !== undefined ? message.body : message.firstLine;
|
|
476
487
|
out(String(message.seq) + ' ' + message.sender + ' ' + text + '\n');
|
|
477
488
|
}
|
|
478
489
|
return 0;
|
package/dist/client.js
CHANGED
|
@@ -35,24 +35,22 @@ 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) => {
|
package/dist/core.js
CHANGED
|
@@ -5,6 +5,10 @@ export { HANDLE_RE };
|
|
|
5
5
|
const GROUP_NAME_RE = /^@?[a-z0-9][a-z0-9-]{1,31}$/;
|
|
6
6
|
const VERDICTS = ['agree', 'disagree', 'info'];
|
|
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.
|
|
@@ -165,7 +169,7 @@ export class MurmurCore {
|
|
|
165
169
|
const stripped = stripGroupPrefix(entry);
|
|
166
170
|
const group = this.store.listGroups().find((g) => g.name === stripped);
|
|
167
171
|
if (!entry.startsWith('@') && (group === undefined || this.store.getPeer(entry) !== null)) {
|
|
168
|
-
add(entry);
|
|
172
|
+
add(this.store.getPeer(entry) === null ? this.handleForName(entry) : entry);
|
|
169
173
|
continue;
|
|
170
174
|
}
|
|
171
175
|
if (group === undefined) {
|
|
@@ -180,6 +184,21 @@ export class MurmurCore {
|
|
|
180
184
|
}
|
|
181
185
|
return out;
|
|
182
186
|
}
|
|
187
|
+
// A bare name that is no handle: a session's display name (case-insensitive)
|
|
188
|
+
// or a name whose slug is a handle. Several matches are ambiguous. No match
|
|
189
|
+
// keeps the plain unknown handle error.
|
|
190
|
+
handleForName(name) {
|
|
191
|
+
const lower = name.toLowerCase();
|
|
192
|
+
const slug = slugify(name);
|
|
193
|
+
const found = this.store
|
|
194
|
+
.listPeers()
|
|
195
|
+
.filter((p) => p.handle === slug || p.display?.toLowerCase() === lower)
|
|
196
|
+
.map((p) => p.handle);
|
|
197
|
+
if (found.length > 1) {
|
|
198
|
+
throw new MurmurError('bad_request', 'ambiguous name ' + name + ', use one of: ' + found.join(', '));
|
|
199
|
+
}
|
|
200
|
+
return found[0] ?? name;
|
|
201
|
+
}
|
|
183
202
|
// Rate, duplicate and cap checks for one intended send. A send that passes
|
|
184
203
|
// every check consumes one rate slot and one duplicate fingerprint; a send
|
|
185
204
|
// rejected by any check consumes none.
|
|
@@ -200,9 +219,9 @@ export class MurmurCore {
|
|
|
200
219
|
throw new MurmurError('cap_thread', 'thread ' + String(threadId) + ' already holds ' + String(THREAD_CAP) + ' messages');
|
|
201
220
|
}
|
|
202
221
|
for (const recipient of recipients) {
|
|
203
|
-
const
|
|
204
|
-
if (
|
|
205
|
-
throw new MurmurError('cap_inbox', 'recipient ' + recipient + ' already has ' + String(
|
|
222
|
+
const backlog = this.store.deliveryStatesForRecipient(recipient, BACKLOG_STATES);
|
|
223
|
+
if (backlog >= UNREAD_CAP) {
|
|
224
|
+
throw new MurmurError('cap_inbox', 'recipient ' + recipient + ' already has ' + String(backlog) + ' deliveries waiting (queued or sent)');
|
|
206
225
|
}
|
|
207
226
|
}
|
|
208
227
|
recent.push(ts);
|
|
@@ -277,9 +296,9 @@ export class MurmurCore {
|
|
|
277
296
|
}
|
|
278
297
|
return this.store.getNativeTransport(recipient) !== null ? 'native' : 'connection';
|
|
279
298
|
}
|
|
280
|
-
// A reply
|
|
281
|
-
//
|
|
282
|
-
//
|
|
299
|
+
// A reply is stored once in the thread; only the ones waiting for it are
|
|
300
|
+
// delivered it (in the parent's delivery mode). Everyone else in the thread
|
|
301
|
+
// reads it with the thread view.
|
|
283
302
|
reply(sender, arg) {
|
|
284
303
|
if (arg.verdict !== undefined && !VERDICTS.includes(arg.verdict)) {
|
|
285
304
|
throw new MurmurError('bad_request', 'invalid verdict: ' + arg.verdict);
|
|
@@ -288,15 +307,14 @@ export class MurmurCore {
|
|
|
288
307
|
if (parent === null) {
|
|
289
308
|
throw new MurmurError('unknown_message', 'unknown message: ' + String(arg.messageId));
|
|
290
309
|
}
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
const recipients = [...participants].filter((handle) => this.store.getPeer(handle) !== null);
|
|
310
|
+
// Only the ones waiting for this reply get a row: the author of the message
|
|
311
|
+
// it answers plus the session that message was typed in. A reply inside
|
|
312
|
+
// its own thread (the replier wrote the parent) goes to the parent's recipients.
|
|
313
|
+
const waiting = new Set(parent.sender === sender
|
|
314
|
+
? this.store.getDeliveries(parent.id).map((d) => d.recipient)
|
|
315
|
+
: [parent.sender, ...(parent.via === null ? [] : [parent.via])]);
|
|
316
|
+
waiting.delete(sender);
|
|
317
|
+
const recipients = [...waiting].filter((handle) => this.store.getPeer(handle) !== null);
|
|
300
318
|
this.checkLimits(sender, arg.body, recipients, parent.threadId);
|
|
301
319
|
const mode = parent.mode;
|
|
302
320
|
const ts = this.nowMs();
|
|
@@ -418,13 +436,20 @@ export class MurmurCore {
|
|
|
418
436
|
threads.sort((a, b) => b.latestSeq - a.latestSeq);
|
|
419
437
|
return { handle, unreadTotal, threads };
|
|
420
438
|
}
|
|
421
|
-
threadView(threadId, sinceSeq, full = true) {
|
|
439
|
+
threadView(threadId, sinceSeq, full = true, messageId) {
|
|
422
440
|
const all = this.store.threadMessages(threadId, null);
|
|
423
441
|
if (all.length === 0) {
|
|
424
442
|
throw new MurmurError('unknown_thread', 'unknown thread: ' + String(threadId));
|
|
425
443
|
}
|
|
426
444
|
const last = all[all.length - 1];
|
|
427
445
|
const latestSeq = last === undefined ? 0 : last.seq;
|
|
446
|
+
if (messageId !== undefined) {
|
|
447
|
+
if (!all.some((row) => row.id === messageId)) {
|
|
448
|
+
throw new MurmurError('bad_request', 'message ' + String(messageId) + ' is not in thread ' + String(threadId));
|
|
449
|
+
}
|
|
450
|
+
const asked = all.filter((row) => row.id === messageId || row.inReplyTo === messageId);
|
|
451
|
+
return { threadId, latestSeq, messages: asked.map((row) => ({ ...summaryOf(row), body: row.deliveredBody })) };
|
|
452
|
+
}
|
|
428
453
|
const rows = sinceSeq === null ? all : this.store.threadMessages(threadId, sinceSeq);
|
|
429
454
|
return { threadId, latestSeq, messages: rows.map(full ? fullOf : summaryOf) };
|
|
430
455
|
}
|
|
@@ -810,11 +835,14 @@ export class MurmurCore {
|
|
|
810
835
|
}
|
|
811
836
|
// The hook injection pull: queued push-mode messages, newest first,
|
|
812
837
|
// marked delivered as they are handed out, each with its rendered text.
|
|
813
|
-
pendingPush(handle, limit) {
|
|
838
|
+
pendingPush(handle, limit, skip = () => false) {
|
|
814
839
|
const ts = this.nowMs();
|
|
815
840
|
const messages = [];
|
|
816
841
|
const texts = [];
|
|
817
842
|
for (const { message: row } of this.store.pendingPushFor(handle, limit)) {
|
|
843
|
+
if (skip(row.id)) {
|
|
844
|
+
continue;
|
|
845
|
+
}
|
|
818
846
|
this.store.markDelivered(row.id, handle, ts);
|
|
819
847
|
this.events.onStateChange({ threadId: row.threadId, recipient: handle, from: 'queued', to: 'delivered' });
|
|
820
848
|
const message = fullOf(row);
|
package/dist/install.js
CHANGED
|
@@ -12,6 +12,7 @@ const PRE_EXEC_COMMAND_MD = `---
|
|
|
12
12
|
description: Send to a murmur group or peer as the owner; bare lists peers and groups
|
|
13
13
|
argument-hint: <group | @group | handle[,more]> <message>
|
|
14
14
|
allowed-tools: Bash(murmur slash:*)
|
|
15
|
+
disable-model-invocation: true
|
|
15
16
|
---
|
|
16
17
|
|
|
17
18
|
\`\`\`!
|
|
@@ -106,7 +107,8 @@ function installClaude(home) {
|
|
|
106
107
|
writeTextFile(commandPath, PRE_EXEC_COMMAND_MD);
|
|
107
108
|
const claudeJsonPath = join(home, '.claude.json');
|
|
108
109
|
const claudeJson = readJsonObject(claudeJsonPath);
|
|
109
|
-
|
|
110
|
+
// alwaysLoad keeps the tool schemas in the prompt instead of behind ToolSearch (one call less per use).
|
|
111
|
+
mergeMcpServer(objectAt(claudeJson, 'mcpServers', claudeJsonPath), { alwaysLoad: true });
|
|
110
112
|
writeJsonFile(claudeJsonPath, claudeJson);
|
|
111
113
|
const settingsPath = join(home, '.claude', 'settings.json');
|
|
112
114
|
const settings = readJsonObject(settingsPath);
|
|
@@ -219,13 +221,13 @@ function objectAt(parent, key, file) {
|
|
|
219
221
|
// The murmur server entry, keeping any env the user added but dropping the
|
|
220
222
|
// per-session handle placeholder older versions wrote: identity now comes
|
|
221
223
|
// from the session's host process.
|
|
222
|
-
function mergeMcpServer(servers) {
|
|
224
|
+
function mergeMcpServer(servers, extra = {}) {
|
|
223
225
|
const existing = servers.murmur;
|
|
224
226
|
const env = isRecord(existing) && isRecord(existing.env) ? { ...existing.env } : {};
|
|
225
227
|
if (env.MURMUR_HANDLE === 'CHANGE-ME-per-session') {
|
|
226
228
|
delete env.MURMUR_HANDLE;
|
|
227
229
|
}
|
|
228
|
-
servers.murmur = Object.keys(env).length > 0 ? { ...MCP_ENTRY, env } : { ...MCP_ENTRY };
|
|
230
|
+
servers.murmur = Object.keys(env).length > 0 ? { ...MCP_ENTRY, ...extra, env } : { ...MCP_ENTRY, ...extra };
|
|
229
231
|
}
|
|
230
232
|
// Claude-style hook maps: event name to a list of { matcher?, hooks: [...] }.
|
|
231
233
|
function mergeHooks(hooks, specs) {
|
package/dist/mcp.js
CHANGED
|
@@ -14,9 +14,11 @@ import { HANDLE_RE, MurmurError, WAIT_DEFAULT_MS, WAIT_MAX_MS } from './protocol
|
|
|
14
14
|
// src/mcp.ts and dist/mcp.js both sit one level below package.json.
|
|
15
15
|
const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
|
|
16
16
|
const INSTRUCTIONS = 'murmur connects this session with other agent sessions on this machine. To consult more than one, send ONE ' +
|
|
17
|
-
'murmur_send to all of them
|
|
18
|
-
'
|
|
19
|
-
'
|
|
17
|
+
'murmur_send (wait: all_replied) to all of them, not separate SendMessage calls. Messages for you arrive ' +
|
|
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.';
|
|
20
|
+
// Claude Code never defers these tools behind ToolSearch.
|
|
21
|
+
const META = { 'anthropic/alwaysLoad': true };
|
|
20
22
|
function textResult(value) {
|
|
21
23
|
return { content: [{ type: 'text', text: JSON.stringify(value) }] };
|
|
22
24
|
}
|
|
@@ -41,6 +43,7 @@ export function identityFor(host, env, cwd) {
|
|
|
41
43
|
export function buildMcpServer(client, identity = {}) {
|
|
42
44
|
const server = new McpServer({ name: 'murmur', version: VERSION }, { instructions: INSTRUCTIONS });
|
|
43
45
|
server.registerTool('murmur_name', {
|
|
46
|
+
_meta: META,
|
|
44
47
|
description: 'Rename this session on the bus (keeps its messages and groups), optionally with a display name and role.',
|
|
45
48
|
inputSchema: {
|
|
46
49
|
handle: z.string().min(1),
|
|
@@ -58,13 +61,16 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
58
61
|
return textResult(await client.request(msg));
|
|
59
62
|
});
|
|
60
63
|
server.registerTool('murmur_send', {
|
|
61
|
-
|
|
64
|
+
_meta: META,
|
|
65
|
+
description: 'Send one message to any mix of handles, session names and groups (bare name or @name); one send fans out to all. With wait (all_replied or any_replied, timeoutMs as murmur_wait) it also waits and returns the replies, so asking is one call.',
|
|
62
66
|
inputSchema: {
|
|
63
67
|
threadId: z.number().int().optional(),
|
|
64
68
|
to: z.array(z.string().min(1)).min(1),
|
|
65
69
|
body: z.string().min(1),
|
|
66
70
|
references: z.array(z.string()).optional(),
|
|
67
71
|
mode: z.enum(['push', 'notify', 'silent']).optional(),
|
|
72
|
+
wait: z.enum(['all_replied', 'any_replied']).optional(),
|
|
73
|
+
timeoutMs: z.number().int().min(0).optional(),
|
|
68
74
|
},
|
|
69
75
|
}, async (args) => {
|
|
70
76
|
const msg = {
|
|
@@ -79,10 +85,21 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
79
85
|
if (args.mode !== undefined) {
|
|
80
86
|
msg.mode = args.mode;
|
|
81
87
|
}
|
|
82
|
-
|
|
88
|
+
const sent = await client.request(msg);
|
|
89
|
+
if (args.wait === undefined) {
|
|
90
|
+
return textResult(sent);
|
|
91
|
+
}
|
|
92
|
+
const waitMsg = {
|
|
93
|
+
type: 'wait',
|
|
94
|
+
threadId: sent.threadId,
|
|
95
|
+
until: args.wait,
|
|
96
|
+
timeoutMs: Math.min(args.timeoutMs ?? WAIT_DEFAULT_MS, WAIT_MAX_MS),
|
|
97
|
+
};
|
|
98
|
+
return textResult({ sent, wait: await client.request(waitMsg) });
|
|
83
99
|
});
|
|
84
100
|
server.registerTool('murmur_reply', {
|
|
85
|
-
|
|
101
|
+
_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, DISAGREE or INFO and set verdict to match.',
|
|
86
103
|
inputSchema: {
|
|
87
104
|
messageId: z.number().int(),
|
|
88
105
|
body: z.string().min(1),
|
|
@@ -100,6 +117,7 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
100
117
|
return textResult(await client.request(msg));
|
|
101
118
|
});
|
|
102
119
|
server.registerTool('murmur_ack', {
|
|
120
|
+
_meta: META,
|
|
103
121
|
description: 'Tell senders you saw these messages and will answer later.',
|
|
104
122
|
inputSchema: {
|
|
105
123
|
ids: z.array(z.number().int()).min(1),
|
|
@@ -109,11 +127,13 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
109
127
|
return textResult(await client.request(msg));
|
|
110
128
|
});
|
|
111
129
|
server.registerTool('murmur_thread', {
|
|
112
|
-
|
|
130
|
+
_meta: META,
|
|
131
|
+
description: 'Read a thread: first lines by default, full bodies with full, only newer than sinceSeq. With messageId, only that message and the replies to it (the question you care about), full bodies.',
|
|
113
132
|
inputSchema: {
|
|
114
133
|
threadId: z.number().int(),
|
|
115
134
|
sinceSeq: z.number().int().optional(),
|
|
116
135
|
full: z.boolean().optional(),
|
|
136
|
+
messageId: z.number().int().optional(),
|
|
117
137
|
},
|
|
118
138
|
}, async (args) => {
|
|
119
139
|
const msg = {
|
|
@@ -121,11 +141,13 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
121
141
|
threadId: args.threadId,
|
|
122
142
|
sinceSeq: args.sinceSeq ?? null,
|
|
123
143
|
full: args.full ?? false,
|
|
144
|
+
...(args.messageId !== undefined ? { messageId: args.messageId } : {}),
|
|
124
145
|
};
|
|
125
146
|
return textResult(await client.request(msg));
|
|
126
147
|
});
|
|
127
148
|
server.registerTool('murmur_wait', {
|
|
128
|
-
|
|
149
|
+
_meta: META,
|
|
150
|
+
description: 'Who got, read and answered the latest ask, with verdicts and latencies, plus the text of the replies addressed to you. Waits until all_replied or any_replied, up to timeoutMs (default 120000, max 300000; 0 returns now).',
|
|
129
151
|
inputSchema: {
|
|
130
152
|
threadId: z.number().int(),
|
|
131
153
|
until: z.enum(['all_replied', 'any_replied']),
|
|
@@ -142,6 +164,7 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
142
164
|
return textResult(await client.request(msg));
|
|
143
165
|
});
|
|
144
166
|
server.registerTool('murmur_groups', {
|
|
167
|
+
_meta: META,
|
|
145
168
|
description: 'Create, list, add to, remove from, or delete a group. Deleting never touches sessions or history.',
|
|
146
169
|
inputSchema: {
|
|
147
170
|
action: z.enum(['create', 'list', 'add', 'remove', 'delete']),
|
|
@@ -159,6 +182,7 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
159
182
|
return textResult(await client.request(msg));
|
|
160
183
|
});
|
|
161
184
|
server.registerTool('murmur_status', {
|
|
185
|
+
_meta: META,
|
|
162
186
|
description: 'Every peer with presence (busy, idle, online, offline), its CLI and unread counts.',
|
|
163
187
|
}, async () => {
|
|
164
188
|
const msg = { type: 'status' };
|
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/dist/protocol.js
CHANGED
|
@@ -72,8 +72,8 @@ export function deliveryTag(messageId) {
|
|
|
72
72
|
return '[murmur m' + String(messageId) + ' ';
|
|
73
73
|
}
|
|
74
74
|
export function replyFooter(m) {
|
|
75
|
-
return ('(
|
|
76
|
-
' <text>;
|
|
75
|
+
return ('(answer with murmur_reply messageId ' + String(m.id) + ', plain text never reaches the sender; from a shell: murmur reply ' +
|
|
76
|
+
String(m.id) + ' <text>; its replies: murmur_thread ' + String(m.threadId) + ' messageId ' + String(m.id) + ')');
|
|
77
77
|
}
|
|
78
78
|
// What a session sees for one message, on every transport: a tag line with
|
|
79
79
|
// ids, sender and recipients, the (possibly truncated) body, references, and
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "murmur-it",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
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
|
}
|