murmur-it 0.2.1 → 0.2.3

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 CHANGED
@@ -1,8 +1,51 @@
1
1
  # Changelog
2
2
 
3
- All notable changes to murmur are documented here. The format follows
4
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
- [Semantic Versioning](https://semver.org/).
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.3] - 2026-10-20
6
+
7
+ ### Changed
8
+
9
+ - 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).
10
+ - `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.
11
+ - `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.
12
+ - The MCP instructions, the `murmur_reply` and `murmur_wait` descriptions, the opencode and Hummin adapter descriptions and the docs describe this routing.
13
+ - 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).
14
+ - 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.
15
+ - `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.
16
+ - `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.
17
+ - 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.
18
+ - `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.
19
+
20
+ ### Fixed
21
+
22
+ - 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.
23
+ - 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.
24
+
25
+ ### Added
26
+
27
+ - `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`.
28
+ - 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.
29
+
30
+ ## [0.2.2] - 2026-10-20
31
+
32
+ ### Fixed
33
+
34
+ - `/murmur` now reads as coming from the owner through the session it was typed in: the message tag is `from renn via <session>`, and replies are pushed into that session as well as to `renn`. Before, replies to an owner message went only to `renn`, which has no session, so the session the human typed in never saw them. From a plain terminal (no session among the ancestors) nothing changes.
35
+ - A rename now carries the whole session: every live broker connection bound to the old handle (the session's MCP server, an adapter) follows to the new one, so its presence and later sends use the new name. Pending delivery proof and batched notifications follow the rename too.
36
+
37
+ ### Added
38
+
39
+ - Claude sessions take the name the user gave them. The hook reads the last 256 KB of the transcript, takes the latest `customTitle` and sends it as `title`; the session's handle becomes its slug (`Ledger, Implementer, Companion - Claude 3` becomes `ledger-implementer-companion-claude-3`) and its display the full title. It follows a later `/rename` only while the handle is automatic: `murmur_name` and `murmur name` pin it. A slug held by another live session keeps the current handle.
40
+ - `via` on messages, thread views, `MessageSummary` and `SendResult`, backed by a nullable `messages.via` column.
41
+ - `murmur prune` and the `prune` protocol request: removes peers that are not the owner and have no session, message, delivery, group membership or live connection (the v0.1 `claude-<8 hex>` leftovers), and prints the removed handles.
42
+ - Schema migration: `messages.via` and `sessions.pinned` are added to an existing database when `PRAGMA table_info` lacks them.
43
+
44
+ ### Changed
45
+
46
+ - Handles may be up to 48 characters (`^[a-z0-9][a-z0-9-]{1,47}$`), up from 32, so title slugs fit.
47
+ - The MCP instructions and the `murmur_send` description tell agents to consult several sessions with one `murmur_send` to all of them instead of separate `SendMessage` calls.
48
+ - Hummin's model-free `/murmur` passes its process as the ancestor, so its messages carry the session as `via`.
6
49
 
7
50
  ## [0.2.1] - 2026-10-20
8
51
 
@@ -61,6 +104,8 @@ All notable changes to murmur are documented here. The format follows
61
104
  - Limits: send rate, duplicate window, thread and inbox caps.
62
105
  - 283 tests at 100 percent lines and branches, and an end-to-end rig that replayed the live 3-peer scenario.
63
106
 
107
+ [0.2.3]: https://github.com/rennf93/murmur/releases/tag/v0.2.3
108
+ [0.2.2]: https://github.com/rennf93/murmur/releases/tag/v0.2.2
64
109
  [0.2.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1
65
110
  [0.2.1-rc.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1-rc.1
66
111
  [0.2.0]: https://github.com/rennf93/murmur/releases/tag/v0.2.0
package/README.md CHANGED
@@ -1,33 +1,79 @@
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">
4
+
1
5
  # murmur
2
6
 
3
- 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 reaches everyone in the thread. 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.
7
+ A local message bus so AI CLI sessions talk in group threads.
4
8
 
5
- 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), and any process that can run a shell command can use the `murmur` CLI.
9
+ [![npm](https://img.shields.io/npm/v/murmur-it)](https://www.npmjs.com/package/murmur-it)
10
+ [![CI](https://github.com/rennf93/murmur/actions/workflows/ci.yml/badge.svg)](https://github.com/rennf93/murmur/actions/workflows/ci.yml)
11
+ [![License](https://img.shields.io/npm/l/murmur-it)](https://github.com/rennf93/murmur/blob/master/LICENSE)
12
+ [![Docs](https://img.shields.io/badge/docs-rennf93.github.io%2Fmurmur-blue)](https://rennf93.github.io/murmur/)
13
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/rennf93/murmur/badge)](https://scorecard.dev/viewer/?uri=github.com/rennf93/murmur)
6
14
 
7
- Full documentation: https://rennf93.github.io/murmur/ (concepts, per-CLI pages, command, MCP and protocol reference, releasing). See also [CHANGELOG.md](CHANGELOG.md), [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
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)
8
16
 
9
- ## Install
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
+ ![Terminal recording: a group, one send, two replies from simulated peers, the thread and the status](https://raw.githubusercontent.com/rennf93/murmur/master/docs/assets/demo.gif)
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
10
28
 
11
29
  Requires Node 20 or newer.
12
30
 
13
31
  ```
14
- npm install -g murmur-it # the package is murmur-it; the command it installs is murmur
15
- murmur init # ~/.murmur (0700), token (0600), murmur.db, owner peer
16
- murmur install claude # and/or: codex | gemini | zcode | opencode | hummin
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
35
+ ```
36
+
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?
17
41
  ```
18
42
 
19
- From source instead: `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`).
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`).
20
66
 
21
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.
22
68
 
23
- 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):
24
70
 
25
71
  | CLI | Files | Notes |
26
72
  | --- | --- | --- |
27
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. |
28
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`. |
29
75
  | gemini | `~/.gemini/settings.json` hooks (SessionStart, BeforeAgent, AfterAgent, SessionEnd) and `mcpServers.murmur`, `~/.gemini/commands/murmur.toml` | |
30
- | `zcode` | Hooks fire under workspace trust; the session announces; one message is handed over by a hook and answered | BLOCKED: the provider answers 429 "Insufficient balance or no resource package. Please recharge." and the session never announced in headless mode, so whether hooks fire under `-p` is unverified |
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. |
31
77
  | opencode | `~/.config/opencode/plugins/murmur.ts`, `~/.config/opencode/commands/murmur.md` | The plugin is the whole integration (tools, push, presence). |
32
78
  | hummin | `~/.hummin/agent/extensions/murmur.ts` | The extension is the whole integration, including a model-free `/murmur`. |
33
79
 
@@ -38,7 +84,9 @@ Every hook, MCP server and CLI command walks up its process ancestors and takes
38
84
  - A new session is named `<cli>-<folder>` (`claude-murmur`, `codex-guard-core`), then `-2`, `-3` for more live sessions in that folder. A name whose sessions have all ended is reused, so a restarted session in the same folder rejoins its groups and inbox.
39
85
  - Rename with the `murmur_name` tool, or `murmur name <handle>` from the session's shell. A rename keeps every message, delivery and group membership. Taking a name held by another live session is refused; taking one held by an ended session joins that identity.
40
86
  - Resume (same CLI session id, new process) and clear (new id, same process) keep the name.
41
- - `murmur send` and `murmur reply` run from an agent's shell speak as that agent's session; run from a plain terminal they speak as the owner. `--as <handle>` overrides. `/murmur` always speaks as the owner, because it is you typing.
87
+ - `murmur send` and `murmur reply` run from an agent's shell speak as that agent's session; run from a plain terminal they speak as the owner. `--as <handle>` overrides. `/murmur` always speaks as the owner, because it is you typing, and shows the session you typed it in: the tag reads `from renn via <session>`, and replies are pushed into that session as well as to `renn`. From a plain terminal there is no session and no `via`.
88
+ - A Claude session takes the name the user gave it (its `/rename` title): the hook reads the latest `customTitle` from the tail of the transcript, the handle becomes its slug (`Ledger, Implementer, Companion - Claude 3` is `ledger-implementer-companion-claude-3`) and the display name the full title. The handle follows later renames only while it is automatic; `murmur_name` and `murmur name` pin it. A slug held by another live session keeps the current handle.
89
+ - Handles are 1 to 48 characters: `^[a-z0-9][a-z0-9-]{1,47}$`.
42
90
 
43
91
  ## Delivery truth table
44
92
 
@@ -46,12 +94,12 @@ Delivery states, per recipient: `queued` (stored, nothing left the broker), `sen
46
94
 
47
95
  | CLI | Live push into a running session | Waiting messages also arrive | Evidence for `delivered` |
48
96
  | --- | --- | --- | --- |
49
- | 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 |
50
- | 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 |
51
- | opencode | Plugin posts the message into the session with `promptAsync` | When the plugin (re)connects | The plugin confirms the post succeeded |
52
- | 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 |
53
- | 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 |
54
- | `zcode` | Hooks fire under workspace trust; the session announces; one message is handed over by a hook and answered | BLOCKED: the provider answers 429 "Insufficient balance or no resource package. Please recharge." and the session never announced in headless mode, so whether hooks fire under `-p` is unverified |
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) |
55
103
 
56
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.
57
105
 
@@ -60,15 +108,15 @@ What a session sees for every message, on every path:
60
108
  ```
61
109
  [murmur m42 t7 s0 from ledger-3 to archify-2, prs-5]
62
110
  <body, cut at 4000 characters with a pointer to the full text>
63
- (reply: murmur_reply messageId 42, or from a shell: murmur reply 42 <text>; whole thread: murmur_thread 7)
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)
64
112
  ```
65
113
 
66
114
  ## Threads, groups, verdicts
67
115
 
68
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.
69
- - Replies go to everyone in the thread (every sender and recipient so far), in the parent's mode, so peers see each other's answers without relaying.
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.
70
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`.
71
- - 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).
72
120
  - `references` carries pointers (paths, commits, URLs) so artifacts stay in their repos.
73
121
  - Groups: create, list, add, remove, delete. Deleting a group never touches sessions, threads or history.
74
122
 
@@ -81,11 +129,7 @@ The human surface, as the owner:
81
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.
82
130
  - `murmur send <targets> <body...> [--mode push|notify|silent] [--refs a,b] [--thread <id>] [--as <handle>]`
83
131
  - `murmur reply <id> <body...> [--verdict agree|disagree|info] [--refs a,b] [--as <handle>]`
84
- - `murmur status`, `murmur thread <id> [--since <seq>] [--full]`, `murmur groups [list|create|add|remove|delete] ...`, `murmur name <handle>`
85
-
86
- ## Doctrine
87
-
88
- 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)
89
133
 
90
134
  ## Limits
91
135
 
@@ -111,7 +155,7 @@ The bus removes two costs and must never remove a third thing. The costs: duplic
111
155
 
112
156
  | Check | What it proves | Last result (2026-10-20) |
113
157
  | --- | --- | --- |
114
- | `claude` | Two sessions announce with native transports; one message to both goes sent, delivered (tag in each transcript), replied; each reply fans out to the other session and the owner; `/murmur` stores `$(...)`, backticks, quotes, `!` and `$HOME` verbatim | PASS, haiku, replies in about 3.6 s |
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 |
115
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 |
116
160
  | `hummin` | The extension injects, acks delivered, carries the reply; the model-free `/murmur` | PASS, zai/glm-5.3-flash, 6.0 s |
117
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) |
@@ -275,7 +275,7 @@ export default function murmur(pi: ExtensionAPI): void {
275
275
  let c: Client | undefined;
276
276
  try {
277
277
  c = await openClient(() => {}, () => {});
278
- await c.request({ type: "register", clientKind: "cli", owner: true });
278
+ await c.request({ type: "register", clientKind: "cli", owner: true, ancestors: [process.pid] });
279
279
  return await run(c);
280
280
  } catch (e) {
281
281
  return `murmur: ${String(e instanceof Error ? e.message : e)}`;
@@ -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; the reply reaches everyone in the thread, 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 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; the reply reaches everyone in the thread, 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 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) {
@@ -220,6 +222,7 @@ export class Broker {
220
222
  reader: new LineReader(),
221
223
  authenticated: false,
222
224
  handle: null,
225
+ via: null,
223
226
  live: false,
224
227
  listening: false,
225
228
  pendingHost: null,
@@ -270,6 +273,7 @@ export class Broker {
270
273
  }
271
274
  onSocketClose(conn) {
272
275
  this.conns.delete(conn);
276
+ const unresolved = conn.waiters.size > 0;
273
277
  for (const waiter of [...conn.waiters]) {
274
278
  clearTimeout(waiter.timer);
275
279
  this.removeWaiter(waiter);
@@ -277,6 +281,10 @@ export class Broker {
277
281
  if (conn.handle !== null && this.presence.get(conn.handle) === conn) {
278
282
  this.presence.delete(conn.handle);
279
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
+ }
280
288
  // Stamp nothing on close; only register refreshes last_seen_at. Only a
281
289
  // long-lived connection going away means the peer went away.
282
290
  if (conn.handle !== null && conn.live && !this.stopped) {
@@ -403,6 +411,9 @@ export class Broker {
403
411
  case 'status':
404
412
  this.replyOk(conn.socket, id, this.handleStatus());
405
413
  return;
414
+ case 'prune':
415
+ this.replyOk(conn.socket, id, this.handlePrune());
416
+ return;
406
417
  case 'fetch-push':
407
418
  this.replyOk(conn.socket, id, this.handleFetchPush(rec));
408
419
  return;
@@ -424,8 +435,12 @@ export class Broker {
424
435
  const owner = optBool(rec, 'owner') === true;
425
436
  const live = kind === 'mcp' || kind === 'adapter';
426
437
  let resolved;
438
+ conn.via = null;
427
439
  if (owner) {
428
440
  resolved = this.ownerHandle();
441
+ if (ancestors !== undefined) {
442
+ conn.via = this.core.sessionForAncestors(ancestors)?.handle ?? null;
443
+ }
429
444
  }
430
445
  else if (host !== undefined) {
431
446
  const session = this.core.sessionForHost(host);
@@ -439,6 +454,7 @@ export class Broker {
439
454
  return { handle: '', owner: false };
440
455
  }
441
456
  resolved = handle === undefined ? session.handle : this.core.renameSession(session, handle);
457
+ this.rebind(session.handle, resolved);
442
458
  }
443
459
  else if (ancestors !== undefined && handle === undefined) {
444
460
  resolved = this.core.sessionForAncestors(ancestors)?.handle ?? this.ownerHandle();
@@ -482,6 +498,7 @@ export class Broker {
482
498
  const transcriptPath = optString(rec, 'transcriptPath');
483
499
  const cwd = optString(rec, 'cwd');
484
500
  const handle = optString(rec, 'handle');
501
+ const title = optString(rec, 'title');
485
502
  const listen = optBool(rec, 'listen') === true;
486
503
  let native;
487
504
  if (rec.native !== undefined) {
@@ -491,6 +508,8 @@ export class Broker {
491
508
  const nat = rec.native;
492
509
  native = { socketPath: reqString(nat, 'socketPath'), token: reqString(nat, 'token') };
493
510
  }
511
+ // A title can rename the session, so find the name it had before.
512
+ const before = (cliSessionId === null ? null : this.store.sessionByCliId(client, cliSessionId)) ?? this.store.sessionByHost(host.hostPid, host.hostStart);
494
513
  const session = this.core.sessionEvent({
495
514
  event,
496
515
  client,
@@ -498,9 +517,13 @@ export class Broker {
498
517
  host,
499
518
  ...(transcriptPath !== undefined ? { transcriptPath } : {}),
500
519
  ...(cwd !== undefined ? { cwd } : {}),
520
+ ...(title !== undefined ? { title } : {}),
501
521
  ...(handle !== undefined ? { handle } : {}),
502
522
  ...(native !== undefined ? { native } : {}),
503
523
  });
524
+ if (before !== null) {
525
+ this.rebind(before.handle, session.handle);
526
+ }
504
527
  conn.listening = listen;
505
528
  this.bind(conn, session.handle, listen);
506
529
  // MCP servers of this session that registered before it announced itself.
@@ -551,6 +574,7 @@ export class Broker {
551
574
  threadId,
552
575
  to,
553
576
  body,
577
+ via: conn.via,
554
578
  };
555
579
  if (references !== undefined) {
556
580
  arg.references = references;
@@ -584,7 +608,11 @@ export class Broker {
584
608
  const body = reqString(rec, 'body');
585
609
  const verdict = optEnum(rec, 'verdict', VERDICTS);
586
610
  const references = optStringArray(rec, 'references');
587
- const arg = { messageId, body };
611
+ const arg = {
612
+ messageId,
613
+ body,
614
+ via: conn.via,
615
+ };
588
616
  if (verdict !== undefined) {
589
617
  arg.verdict = verdict;
590
618
  }
@@ -650,7 +678,8 @@ export class Broker {
650
678
  handleThread(rec) {
651
679
  const threadId = reqNumber(rec, 'threadId');
652
680
  const sinceSeq = reqNumberOrNull(rec, 'sinceSeq');
653
- return this.core.threadView(threadId, sinceSeq, reqBool(rec, 'full'));
681
+ const messageId = rec.messageId === undefined ? undefined : reqNumber(rec, 'messageId');
682
+ return this.core.threadView(threadId, sinceSeq, reqBool(rec, 'full'), messageId);
654
683
  }
655
684
  handleCollect(rec) {
656
685
  const threadId = reqNumber(rec, 'threadId');
@@ -671,6 +700,17 @@ export class Broker {
671
700
  handleStatus() {
672
701
  return this.core.status((handle) => ({ online: this.presence.has(handle) }));
673
702
  }
703
+ // Every handle with a connection, so a peer someone is talking through is
704
+ // never pruned.
705
+ handlePrune() {
706
+ const connected = new Set();
707
+ for (const conn of this.conns) {
708
+ if (conn.handle !== null) {
709
+ connected.add(conn.handle);
710
+ }
711
+ }
712
+ return { removed: this.core.prune(connected) };
713
+ }
674
714
  handleFetchPush(rec) {
675
715
  const handle = reqString(rec, 'handle');
676
716
  const limit = reqNumber(rec, 'limit');
@@ -679,7 +719,7 @@ export class Broker {
679
719
  }
680
720
  // Everything the pull hands out was queued, so each one tells its
681
721
  // sender it finally arrived.
682
- const result = this.core.pendingPush(handle, limit);
722
+ const result = this.core.pendingPush(handle, limit, (id) => this.inFlight.has(String(id) + ':' + handle));
683
723
  for (const message of result.messages) {
684
724
  this.enqueueNotification(message.sender, {
685
725
  kind: 'queued_delivered',
@@ -703,7 +743,7 @@ export class Broker {
703
743
  if (this.stopped) {
704
744
  return;
705
745
  }
706
- if (target.kind === 'queued') {
746
+ if (target.kind === 'queued' || this.heldForWait(target.message, target.recipient)) {
707
747
  continue;
708
748
  }
709
749
  await this.pushOne(target.message.id, target.message.threadId, target.recipient, target.text, {
@@ -714,6 +754,22 @@ export class Broker {
714
754
  });
715
755
  }
716
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
+ }
717
773
  async pushOne(messageId, threadId, recipient, text, payload) {
718
774
  const listener = this.presence.get(recipient);
719
775
  if (listener !== undefined && listener.listening && !listener.socket.destroyed) {
@@ -722,6 +778,16 @@ export class Broker {
722
778
  this.markSent(messageId, threadId, recipient);
723
779
  return;
724
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) {
725
791
  const session = this.liveSessionOf(recipient);
726
792
  const transcript = session?.transcriptPath ?? null;
727
793
  const offset = transcript === null ? 0 : ProofWatcher.offsetOf(transcript);
@@ -751,6 +817,9 @@ export class Broker {
751
817
  async pushQueued(handle) {
752
818
  const waiting = this.store.pendingPushFor(handle, 50).reverse();
753
819
  for (const { message } of waiting) {
820
+ if (this.heldForWait(message, handle)) {
821
+ continue;
822
+ }
754
823
  const recipients = this.store.getDeliveries(message.id).map((d) => d.recipient);
755
824
  const full = fullOf(message);
756
825
  const text = renderDelivery(full, message.deliveredBody, recipients);
@@ -883,6 +952,7 @@ export class Broker {
883
952
  conditionMet: true,
884
953
  timedOut: false,
885
954
  matrix: this.matrixFor(threadId),
955
+ replies: this.takeReplies(threadId, conn.handle),
886
956
  });
887
957
  return;
888
958
  }
@@ -891,6 +961,7 @@ export class Broker {
891
961
  id,
892
962
  threadId,
893
963
  until,
964
+ held: new Set(),
894
965
  timer: setTimeout(() => this.resolveTimedOut(waiter), timeoutMs),
895
966
  };
896
967
  conn.waiters.add(waiter);
@@ -918,6 +989,20 @@ export class Broker {
918
989
  }
919
990
  return deliveries.every((d) => d.state === 'replied');
920
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
+ this.markDeliveredHop(row.id, delivery.recipient);
1001
+ replies.push({ id: row.id, seq: row.seq, sender: row.sender, verdict: row.verdict, body: row.deliveredBody });
1002
+ }
1003
+ }
1004
+ return replies;
1005
+ }
921
1006
  // The collect matrix for a WaitResult. A thread without messages or without
922
1007
  // an ask collects nothing, which degrades to an empty matrix.
923
1008
  matrixFor(threadId) {
@@ -954,6 +1039,7 @@ export class Broker {
954
1039
  conditionMet: true,
955
1040
  timedOut: false,
956
1041
  matrix: this.matrixFor(threadId),
1042
+ replies: this.takeReplies(threadId, waiter.conn.handle, waiter.held),
957
1043
  });
958
1044
  }
959
1045
  }
@@ -968,6 +1054,7 @@ export class Broker {
968
1054
  conditionMet: false,
969
1055
  timedOut: true,
970
1056
  matrix: this.matrixFor(waiter.threadId),
1057
+ replies: this.takeReplies(waiter.threadId, waiter.conn.handle, waiter.held),
971
1058
  });
972
1059
  }
973
1060
  catch {
@@ -999,6 +1086,32 @@ export class Broker {
999
1086
  this.presence.set(handle, conn);
1000
1087
  }
1001
1088
  }
1089
+ // A session's name changed: connections still bound to the old one (its MCP
1090
+ // server, an adapter) follow it, unless another live session still holds
1091
+ // it. Ended sessions left on the old name do not count.
1092
+ rebind(from, to) {
1093
+ if (from === to || !this.core.claimable(from, null)) {
1094
+ return;
1095
+ }
1096
+ for (const conn of this.conns) {
1097
+ if (conn.handle === from) {
1098
+ this.bind(conn, to, conn.live);
1099
+ }
1100
+ }
1101
+ // A whole-identity rename moved the deliveries; pending proof and
1102
+ // batched notifications follow them.
1103
+ if (this.store.getPeer(from) === null) {
1104
+ this.proof.rename(from, to);
1105
+ const entry = this.notifyQueue.get(from);
1106
+ if (entry !== undefined) {
1107
+ clearTimeout(entry.timer);
1108
+ this.notifyQueue.delete(from);
1109
+ for (const payload of entry.payloads) {
1110
+ this.enqueueNotification(to, payload);
1111
+ }
1112
+ }
1113
+ }
1114
+ }
1002
1115
  requireBoundHandle(conn) {
1003
1116
  if (conn.handle === null && conn.pendingHost !== null) {
1004
1117
  const { host, client, cwd } = conn.pendingHost;
package/dist/cli.js CHANGED
@@ -11,9 +11,9 @@ 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
- const SLASH_USAGE = '/murmur <group | handle[,more]> <message> (run bare like this for peers and groups)';
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) {
18
18
  // The default io is captured at call time and touches only the real
19
19
  // process streams, so injected io replaces them completely.
@@ -62,6 +62,8 @@ async function dispatch(argv, out, err) {
62
62
  return cmdReply(argv.slice(1), out, err);
63
63
  case 'name':
64
64
  return cmdName(argv.slice(1), out, err);
65
+ case 'prune':
66
+ return cmdPrune(out);
65
67
  case 'slash':
66
68
  return cmdSlash(argv.slice(1), out, err);
67
69
  case 'status':
@@ -90,9 +92,10 @@ function printUsage(err) {
90
92
  ' send <targets> <body...> send a message; flags: --as, --mode, --refs, --thread',
91
93
  ' reply <id> <body...> reply into a thread; flags: --as, --verdict, --refs',
92
94
  ' name <handle> rename the agent session this runs in',
93
- ' slash [args...] the /murmur backing (args or stdin); bare prints peers and groups',
95
+ ' slash [args...] the /murmur backing, sent as the owner via your session; bare prints peers and groups',
96
+ ' prune remove peers with no session, message, group or connection',
94
97
  ' status list peers with presence and unread counts',
95
- ' thread <id> [--since <n>] [--full]',
98
+ ' thread <id> [--since <n>] [--full] [--message <id>]',
96
99
  ' groups [list] | groups create <name> | groups add <name> <members...>',
97
100
  ' | groups remove <name> <members...> | groups delete <name>',
98
101
  ' install <' + INSTALL_CLIENTS.join('|') + '>',
@@ -203,7 +206,13 @@ function identityMessage(asHandle, speaker) {
203
206
  return { type: 'register', handle: asHandle, clientKind: 'cli' };
204
207
  }
205
208
  if (speaker === 'owner') {
206
- return { type: 'register', owner: true, display: OWNER_DISPLAY, clientKind: 'cli' };
209
+ return {
210
+ type: 'register',
211
+ owner: true,
212
+ display: OWNER_DISPLAY,
213
+ clientKind: 'cli',
214
+ ancestors: currentHost()?.ancestors ?? [],
215
+ };
207
216
  }
208
217
  return { type: 'register', clientKind: 'cli', ancestors: currentHost()?.ancestors ?? [] };
209
218
  }
@@ -402,9 +411,26 @@ async function cmdStatus(out) {
402
411
  }
403
412
  return 0;
404
413
  }
414
+ async function cmdPrune(out) {
415
+ const client = await connectCli();
416
+ try {
417
+ const result = await client.request({ type: 'prune' });
418
+ for (const handle of result.removed) {
419
+ out(handle + '\n');
420
+ }
421
+ if (result.removed.length === 0) {
422
+ out('nothing to prune\n');
423
+ }
424
+ return 0;
425
+ }
426
+ finally {
427
+ client.close();
428
+ }
429
+ }
405
430
  async function cmdThread(args, out, err) {
406
431
  let full = false;
407
432
  let sinceSeq = null;
433
+ let messageId;
408
434
  const positionals = [];
409
435
  for (let i = 0; i < args.length; i += 1) {
410
436
  const arg = args[i];
@@ -415,6 +441,16 @@ async function cmdThread(args, out, err) {
415
441
  full = true;
416
442
  continue;
417
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
+ }
418
454
  if (arg === '--since') {
419
455
  const value = args[i + 1];
420
456
  if (value === undefined) {
@@ -444,10 +480,10 @@ async function cmdThread(args, out, err) {
444
480
  }
445
481
  const client = await connectCli();
446
482
  try {
447
- const msg = { type: 'thread', threadId, sinceSeq, full };
483
+ const msg = { type: 'thread', threadId, sinceSeq, full, ...(messageId !== undefined ? { messageId } : {}) };
448
484
  const result = await client.request(msg);
449
485
  for (const message of result.messages) {
450
- const text = full ? message.body : message.firstLine;
486
+ const text = full || messageId !== undefined ? message.body : message.firstLine;
451
487
  out(String(message.seq) + ' ' + message.sender + ' ' + text + '\n');
452
488
  }
453
489
  return 0;
package/dist/core.js CHANGED
@@ -6,6 +6,16 @@ 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
8
  const OFFLINE_AFTER_MS = 5 * 60 * 1000;
9
+ // A session title as a handle: lowercase, runs of anything else become one
10
+ // hyphen, trimmed, cut to the handle limit. Not necessarily a valid handle.
11
+ export function slugify(title) {
12
+ return title
13
+ .toLowerCase()
14
+ .replace(/[^a-z0-9]+/g, '-')
15
+ .replace(/^-+|-+$/g, '')
16
+ .slice(0, 48)
17
+ .replace(/-+$/, '');
18
+ }
9
19
  // Linear interpolation over an ascending list. Null for an empty list.
10
20
  // fraction 0.5 gives the median, 0.95 the p95.
11
21
  export function percentile(sortedValues, fraction) {
@@ -73,6 +83,7 @@ function summaryOf(row) {
73
83
  isReply: row.isReply,
74
84
  inReplyTo: row.inReplyTo,
75
85
  verdict: parseVerdict(row.verdict),
86
+ via: row.via,
76
87
  createdAt: row.createdAt,
77
88
  };
78
89
  }
@@ -154,7 +165,7 @@ export class MurmurCore {
154
165
  const stripped = stripGroupPrefix(entry);
155
166
  const group = this.store.listGroups().find((g) => g.name === stripped);
156
167
  if (!entry.startsWith('@') && (group === undefined || this.store.getPeer(entry) !== null)) {
157
- add(entry);
168
+ add(this.store.getPeer(entry) === null ? this.handleForName(entry) : entry);
158
169
  continue;
159
170
  }
160
171
  if (group === undefined) {
@@ -169,6 +180,21 @@ export class MurmurCore {
169
180
  }
170
181
  return out;
171
182
  }
183
+ // A bare name that is no handle: a session's display name (case-insensitive)
184
+ // or a name whose slug is a handle. Several matches are ambiguous. No match
185
+ // keeps the plain unknown handle error.
186
+ handleForName(name) {
187
+ const lower = name.toLowerCase();
188
+ const slug = slugify(name);
189
+ const found = this.store
190
+ .listPeers()
191
+ .filter((p) => p.handle === slug || p.display?.toLowerCase() === lower)
192
+ .map((p) => p.handle);
193
+ if (found.length > 1) {
194
+ throw new MurmurError('bad_request', 'ambiguous name ' + name + ', use one of: ' + found.join(', '));
195
+ }
196
+ return found[0] ?? name;
197
+ }
172
198
  // Rate, duplicate and cap checks for one intended send. A send that passes
173
199
  // every check consumes one rate slot and one duplicate fingerprint; a send
174
200
  // rejected by any check consumes none.
@@ -226,6 +252,7 @@ export class MurmurCore {
226
252
  isReply: false,
227
253
  inReplyTo: null,
228
254
  verdict: null,
255
+ via: arg.via ?? null,
229
256
  createdAt: ts,
230
257
  });
231
258
  this.store.addDeliveries(appended.id, recipients, ts);
@@ -236,7 +263,7 @@ export class MurmurCore {
236
263
  }
237
264
  const deliveries = this.store.getDeliveries(appended.id).map(deliveryInfoOf);
238
265
  return {
239
- result: { messageId: appended.id, threadId, seq: appended.seq, deliveries },
266
+ result: { messageId: appended.id, threadId, seq: appended.seq, via: row.via, deliveries },
240
267
  pushes: this.pushesFor(row, recipients, mode),
241
268
  };
242
269
  }
@@ -265,9 +292,9 @@ export class MurmurCore {
265
292
  }
266
293
  return this.store.getNativeTransport(recipient) !== null ? 'native' : 'connection';
267
294
  }
268
- // A reply reaches everyone in the thread (every sender and every recipient
269
- // so far, minus the replier) in the parent's delivery mode, so peers see
270
- // each other's answers without anyone relaying them.
295
+ // A reply is stored once in the thread; only the ones waiting for it are
296
+ // delivered it (in the parent's delivery mode). Everyone else in the thread
297
+ // reads it with the thread view.
271
298
  reply(sender, arg) {
272
299
  if (arg.verdict !== undefined && !VERDICTS.includes(arg.verdict)) {
273
300
  throw new MurmurError('bad_request', 'invalid verdict: ' + arg.verdict);
@@ -276,12 +303,14 @@ export class MurmurCore {
276
303
  if (parent === null) {
277
304
  throw new MurmurError('unknown_message', 'unknown message: ' + String(arg.messageId));
278
305
  }
279
- const participants = new Set(this.store.threadRecipientHandles(parent.threadId));
280
- for (const row of this.store.threadMessages(parent.threadId, null)) {
281
- participants.add(row.sender);
282
- }
283
- participants.delete(sender);
284
- const recipients = [...participants].filter((handle) => this.store.getPeer(handle) !== null);
306
+ // Only the ones waiting for this reply get a row: the author of the message
307
+ // it answers plus the session that message was typed in. A reply inside
308
+ // its own thread (the replier wrote the parent) goes to the parent's recipients.
309
+ const waiting = new Set(parent.sender === sender
310
+ ? this.store.getDeliveries(parent.id).map((d) => d.recipient)
311
+ : [parent.sender, ...(parent.via === null ? [] : [parent.via])]);
312
+ waiting.delete(sender);
313
+ const recipients = [...waiting].filter((handle) => this.store.getPeer(handle) !== null);
285
314
  this.checkLimits(sender, arg.body, recipients, parent.threadId);
286
315
  const mode = parent.mode;
287
316
  const ts = this.nowMs();
@@ -297,6 +326,7 @@ export class MurmurCore {
297
326
  isReply: true,
298
327
  inReplyTo: parent.id,
299
328
  verdict: arg.verdict ?? null,
329
+ via: arg.via ?? null,
300
330
  createdAt: ts,
301
331
  });
302
332
  // The sender's own delivery row on the parent message closes the loop:
@@ -402,13 +432,20 @@ export class MurmurCore {
402
432
  threads.sort((a, b) => b.latestSeq - a.latestSeq);
403
433
  return { handle, unreadTotal, threads };
404
434
  }
405
- threadView(threadId, sinceSeq, full = true) {
435
+ threadView(threadId, sinceSeq, full = true, messageId) {
406
436
  const all = this.store.threadMessages(threadId, null);
407
437
  if (all.length === 0) {
408
438
  throw new MurmurError('unknown_thread', 'unknown thread: ' + String(threadId));
409
439
  }
410
440
  const last = all[all.length - 1];
411
441
  const latestSeq = last === undefined ? 0 : last.seq;
442
+ if (messageId !== undefined) {
443
+ if (!all.some((row) => row.id === messageId)) {
444
+ throw new MurmurError('bad_request', 'message ' + String(messageId) + ' is not in thread ' + String(threadId));
445
+ }
446
+ const asked = all.filter((row) => row.id === messageId || row.inReplyTo === messageId);
447
+ return { threadId, latestSeq, messages: asked.map((row) => ({ ...summaryOf(row), body: row.deliveredBody })) };
448
+ }
412
449
  const rows = sinceSeq === null ? all : this.store.threadMessages(threadId, sinceSeq);
413
450
  return { threadId, latestSeq, messages: rows.map(full ? fullOf : summaryOf) };
414
451
  }
@@ -609,7 +646,13 @@ export class MurmurCore {
609
646
  let row = arg.cliSessionId === null ? null : this.store.sessionByCliId(arg.client, arg.cliSessionId);
610
647
  row ??= this.store.sessionByHost(arg.host.hostPid, arg.host.hostStart);
611
648
  if (row === null) {
612
- const handle = arg.handle !== undefined && this.claimable(arg.handle, null) ? arg.handle : this.allocateHandle(arg.client, arg.cwd);
649
+ const explicit = arg.handle !== undefined && this.claimable(arg.handle, null);
650
+ const slug = arg.title === undefined ? '' : slugify(arg.title);
651
+ const handle = explicit
652
+ ? arg.handle
653
+ : this.claimable(slug, null)
654
+ ? slug
655
+ : this.allocateHandle(arg.client, arg.cwd);
613
656
  this.ensurePeer(handle);
614
657
  const id = this.store.insertSession({
615
658
  client: arg.client,
@@ -622,6 +665,9 @@ export class MurmurCore {
622
665
  now: ts,
623
666
  });
624
667
  row = this.store.sessionById(id);
668
+ if (explicit) {
669
+ this.store.updateSession(id, { pinned: 1 });
670
+ }
625
671
  }
626
672
  else {
627
673
  this.store.updateSession(row.id, {
@@ -639,7 +685,10 @@ export class MurmurCore {
639
685
  }
640
686
  const state = arg.event === 'prompt' ? 'busy' : arg.event === 'session-end' ? 'ended' : 'idle';
641
687
  this.store.updateSession(row.id, { state, stateAt: ts });
642
- const fresh = this.store.sessionById(row.id);
688
+ let fresh = this.store.sessionById(row.id);
689
+ if (arg.title !== undefined) {
690
+ fresh = this.followTitle(fresh, arg.title);
691
+ }
643
692
  if (arg.native !== undefined) {
644
693
  this.store.upsertNativeTransport(fresh.handle, arg.native.socketPath, arg.native.token, ts);
645
694
  }
@@ -648,6 +697,19 @@ export class MurmurCore {
648
697
  }
649
698
  return fresh;
650
699
  }
700
+ // The session shows its CLI title as its display name, and takes the title's
701
+ // slug as its handle while the handle is automatic (not pinned by an explicit
702
+ // name) and no other live session holds the slug.
703
+ followTitle(row, title) {
704
+ let current = row;
705
+ const slug = slugify(title);
706
+ if (!row.pinned && slug !== row.handle && this.claimable(slug, row.id)) {
707
+ this.moveSession(row, slug);
708
+ current = this.store.sessionById(row.id);
709
+ }
710
+ this.store.upsertPeer(current.handle, title, null, false, this.nowMs());
711
+ return current;
712
+ }
651
713
  // The session running under this exact host process, if one announced
652
714
  // itself. With create, a missing session is made on the spot (an MCP
653
715
  // server whose hooks never ran still gets an identity).
@@ -677,8 +739,14 @@ export class MurmurCore {
677
739
  // Gives the session a new name. A free name renames the identity with all
678
740
  // its history; a name held by a peer with no live session is taken over
679
741
  // (the session joins that identity, its groups and inbox); a live or
680
- // owner handle is refused.
742
+ // owner handle is refused. An explicit name pins the handle against the
743
+ // CLI's title.
681
744
  renameSession(row, handle) {
745
+ const named = this.moveSession(row, handle);
746
+ this.store.updateSession(row.id, { pinned: 1 });
747
+ return named;
748
+ }
749
+ moveSession(row, handle) {
682
750
  if (!HANDLE_RE.test(handle)) {
683
751
  throw new MurmurError('bad_request', 'invalid handle: ' + handle);
684
752
  }
@@ -699,6 +767,23 @@ export class MurmurCore {
699
767
  }
700
768
  return handle;
701
769
  }
770
+ // Deletes peers nothing refers to: not the owner, no session, no message,
771
+ // delivery or group membership, and no live connection (v0.1 left such
772
+ // rows behind). Returns the removed handles.
773
+ prune(connected) {
774
+ const removed = [];
775
+ for (const peer of this.store.listPeers()) {
776
+ const used = peer.isOwner ||
777
+ connected.has(peer.handle) ||
778
+ this.store.sessionsForHandle(peer.handle).length > 0 ||
779
+ this.store.peerHasHistory(peer.handle);
780
+ if (!used) {
781
+ this.store.deletePeer(peer.handle);
782
+ removed.push(peer.handle);
783
+ }
784
+ }
785
+ return removed;
786
+ }
702
787
  // A handle can be claimed when it is valid, not the owner's, and no live
703
788
  // session other than exceptId holds it.
704
789
  claimable(handle, exceptId) {
@@ -746,11 +831,14 @@ export class MurmurCore {
746
831
  }
747
832
  // The hook injection pull: queued push-mode messages, newest first,
748
833
  // marked delivered as they are handed out, each with its rendered text.
749
- pendingPush(handle, limit) {
834
+ pendingPush(handle, limit, skip = () => false) {
750
835
  const ts = this.nowMs();
751
836
  const messages = [];
752
837
  const texts = [];
753
838
  for (const { message: row } of this.store.pendingPushFor(handle, limit)) {
839
+ if (skip(row.id)) {
840
+ continue;
841
+ }
754
842
  this.store.markDelivered(row.id, handle, ts);
755
843
  this.events.onStateChange({ threadId: row.threadId, recipient: handle, from: 'queued', to: 'delivered' });
756
844
  const message = fullOf(row);
package/dist/hooks.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
1
2
  import { connectBroker } from './client.js';
2
3
  import { getPaths, readToken } from './config.js';
3
4
  import { currentHost } from './proc.js';
@@ -9,6 +10,9 @@ export const HOOK_CLIENTS = ['claude', 'codex', 'gemini', 'zcode'];
9
10
  // pending request and lets the hook return.
10
11
  const HOOK_DEADLINE_MS = 10000;
11
12
  const FETCH_PUSH_LIMIT = 10;
13
+ // Transcripts reach hundreds of MB and Claude repeats the session name as it
14
+ // goes, so only the tail is read: the latest entry is in it.
15
+ const TITLE_TAIL_BYTES = 256 * 1024;
12
16
  // Entry point used by every client's hook config. It must never block or
13
17
  // fail a session: any broker error, broker down, unreadable stdin, unknown
14
18
  // host or unexpected failure resolves with exit 0 and empty stdout.
@@ -67,6 +71,12 @@ function sessionMessage(event, client, input, host, env) {
67
71
  if (input.cwd !== null) {
68
72
  msg.cwd = input.cwd;
69
73
  }
74
+ if (client === 'claude' && input.transcriptPath !== null) {
75
+ const title = readClaudeTitle(input.transcriptPath);
76
+ if (title !== undefined) {
77
+ msg.title = title;
78
+ }
79
+ }
70
80
  const explicit = env.MURMUR_HANDLE;
71
81
  if (typeof explicit === 'string' && explicit.length > 0) {
72
82
  msg.handle = explicit;
@@ -80,6 +90,43 @@ function sessionMessage(event, client, input, host, env) {
80
90
  }
81
91
  return msg;
82
92
  }
93
+ // The name the user gave a Claude session (/rename): the customTitle of the
94
+ // last custom-title entry in the tail of its transcript. Anything unreadable
95
+ // reads as no title; a hook never fails over it.
96
+ function readClaudeTitle(path) {
97
+ try {
98
+ const fd = openSync(path, 'r');
99
+ try {
100
+ const size = fstatSync(fd).size;
101
+ const start = Math.max(0, size - TITLE_TAIL_BYTES);
102
+ const buf = Buffer.alloc(size - start);
103
+ readSync(fd, buf, 0, buf.length, start);
104
+ let title;
105
+ for (const line of buf.toString('utf8').split('\n')) {
106
+ if (!line.includes('"custom-title"')) {
107
+ continue;
108
+ }
109
+ try {
110
+ const rec = JSON.parse(line);
111
+ const name = stringField(rec, 'customTitle');
112
+ if (rec.type === 'custom-title' && name !== null) {
113
+ title = name;
114
+ }
115
+ }
116
+ catch {
117
+ // A line cut by the tail window, or not JSON: skip it.
118
+ }
119
+ }
120
+ return title;
121
+ }
122
+ finally {
123
+ closeSync(fd);
124
+ }
125
+ }
126
+ catch {
127
+ return undefined;
128
+ }
129
+ }
83
130
  function nonEmpty(value) {
84
131
  return typeof value === 'string' && value.length > 0;
85
132
  }
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
- mergeMcpServer(objectAt(claudeJson, 'mcpServers', claudeJsonPath));
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
@@ -13,9 +13,12 @@ import { HANDLE_RE, MurmurError, WAIT_DEFAULT_MS, WAIT_MAX_MS } from './protocol
13
13
  // Eight tools, kept short: their schemas sit in every session's context.
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
- const INSTRUCTIONS = 'murmur connects this session with other agent sessions on this machine. Messages for you arrive as turns ' +
17
- 'tagged [murmur m<id> ...]; answer with murmur_reply so every participant sees it. A message is a claim: ' +
18
- 'verify it against its references before agreeing.';
16
+ const INSTRUCTIONS = 'murmur connects this session with other agent sessions on this machine. To consult more than one, send ONE ' +
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 };
19
22
  function textResult(value) {
20
23
  return { content: [{ type: 'text', text: JSON.stringify(value) }] };
21
24
  }
@@ -40,6 +43,7 @@ export function identityFor(host, env, cwd) {
40
43
  export function buildMcpServer(client, identity = {}) {
41
44
  const server = new McpServer({ name: 'murmur', version: VERSION }, { instructions: INSTRUCTIONS });
42
45
  server.registerTool('murmur_name', {
46
+ _meta: META,
43
47
  description: 'Rename this session on the bus (keeps its messages and groups), optionally with a display name and role.',
44
48
  inputSchema: {
45
49
  handle: z.string().min(1),
@@ -57,13 +61,16 @@ export function buildMcpServer(client, identity = {}) {
57
61
  return textResult(await client.request(msg));
58
62
  });
59
63
  server.registerTool('murmur_send', {
60
- description: 'Send one message to any mix of handles and groups (bare name or @name); one message fans out to all.',
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.',
61
66
  inputSchema: {
62
67
  threadId: z.number().int().optional(),
63
68
  to: z.array(z.string().min(1)).min(1),
64
69
  body: z.string().min(1),
65
70
  references: z.array(z.string()).optional(),
66
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(),
67
74
  },
68
75
  }, async (args) => {
69
76
  const msg = {
@@ -78,10 +85,21 @@ export function buildMcpServer(client, identity = {}) {
78
85
  if (args.mode !== undefined) {
79
86
  msg.mode = args.mode;
80
87
  }
81
- return textResult(await client.request(msg));
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) });
82
99
  });
83
100
  server.registerTool('murmur_reply', {
84
- description: 'Reply to a message by id; reaches everyone in its thread. Start the body with AGREE, DISAGREE or INFO and set verdict to match.',
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.',
85
103
  inputSchema: {
86
104
  messageId: z.number().int(),
87
105
  body: z.string().min(1),
@@ -99,6 +117,7 @@ export function buildMcpServer(client, identity = {}) {
99
117
  return textResult(await client.request(msg));
100
118
  });
101
119
  server.registerTool('murmur_ack', {
120
+ _meta: META,
102
121
  description: 'Tell senders you saw these messages and will answer later.',
103
122
  inputSchema: {
104
123
  ids: z.array(z.number().int()).min(1),
@@ -108,11 +127,13 @@ export function buildMcpServer(client, identity = {}) {
108
127
  return textResult(await client.request(msg));
109
128
  });
110
129
  server.registerTool('murmur_thread', {
111
- description: 'Read a thread: first lines by default, full bodies with full, only newer than sinceSeq.',
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.',
112
132
  inputSchema: {
113
133
  threadId: z.number().int(),
114
134
  sinceSeq: z.number().int().optional(),
115
135
  full: z.boolean().optional(),
136
+ messageId: z.number().int().optional(),
116
137
  },
117
138
  }, async (args) => {
118
139
  const msg = {
@@ -120,11 +141,13 @@ export function buildMcpServer(client, identity = {}) {
120
141
  threadId: args.threadId,
121
142
  sinceSeq: args.sinceSeq ?? null,
122
143
  full: args.full ?? false,
144
+ ...(args.messageId !== undefined ? { messageId: args.messageId } : {}),
123
145
  };
124
146
  return textResult(await client.request(msg));
125
147
  });
126
148
  server.registerTool('murmur_wait', {
127
- description: 'Who got, read and answered the latest ask, with verdicts and latencies. Waits until all_replied or any_replied, up to timeoutMs (default 120000, max 300000; 0 returns now).',
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).',
128
151
  inputSchema: {
129
152
  threadId: z.number().int(),
130
153
  until: z.enum(['all_replied', 'any_replied']),
@@ -141,6 +164,7 @@ export function buildMcpServer(client, identity = {}) {
141
164
  return textResult(await client.request(msg));
142
165
  });
143
166
  server.registerTool('murmur_groups', {
167
+ _meta: META,
144
168
  description: 'Create, list, add to, remove from, or delete a group. Deleting never touches sessions or history.',
145
169
  inputSchema: {
146
170
  action: z.enum(['create', 'list', 'add', 'remove', 'delete']),
@@ -158,6 +182,7 @@ export function buildMcpServer(client, identity = {}) {
158
182
  return textResult(await client.request(msg));
159
183
  });
160
184
  server.registerTool('murmur_status', {
185
+ _meta: META,
161
186
  description: 'Every peer with presence (busy, idle, online, offline), its CLI and unread counts.',
162
187
  }, async () => {
163
188
  const msg = { type: 'status' };
package/dist/proof.js CHANGED
@@ -45,6 +45,16 @@ export class ProofWatcher {
45
45
  }
46
46
  }
47
47
  }
48
+ // The recipient's handle changed: its pending watches follow it.
49
+ rename(from, to) {
50
+ for (const [key, watch] of [...this.watches]) {
51
+ if (watch.recipient === from) {
52
+ this.watches.delete(key);
53
+ watch.recipient = to;
54
+ this.watches.set(String(watch.messageId) + '\u0000' + to, watch);
55
+ }
56
+ }
57
+ }
48
58
  stop() {
49
59
  if (this.timer !== null) {
50
60
  clearInterval(this.timer);
package/dist/protocol.js CHANGED
@@ -11,7 +11,7 @@ export const NOTIFY_BATCH_MS = 60000;
11
11
  export const WAIT_MAX_MS = 300000;
12
12
  export const WAIT_DEFAULT_MS = 120000;
13
13
  export const FIRST_LINE_MAX = 120;
14
- export const HANDLE_RE = /^[a-z0-9][a-z0-9-]{1,31}$/;
14
+ export const HANDLE_RE = /^[a-z0-9][a-z0-9-]{1,47}$/;
15
15
  // How long the broker keeps polling a receiver's transcript for proof after
16
16
  // a push; later hook events of that session re-check without a deadline.
17
17
  export const PROOF_POLL_MS = 120000;
@@ -72,14 +72,17 @@ export function deliveryTag(messageId) {
72
72
  return '[murmur m' + String(messageId) + ' ';
73
73
  }
74
74
  export function replyFooter(m) {
75
- return ('(reply: murmur_reply messageId ' + String(m.id) + ', or from a shell: murmur reply ' + String(m.id) +
76
- ' <text>; whole thread: murmur_thread ' + String(m.threadId) + ')');
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
80
80
  // how to reply.
81
81
  export function renderDelivery(m, deliveredBody, recipients) {
82
82
  let head = deliveryTag(m.id) + 't' + String(m.threadId) + ' s' + String(m.seq) + ' from ' + m.sender;
83
+ if (m.via !== null) {
84
+ head += ' via ' + m.via;
85
+ }
83
86
  if (m.inReplyTo !== null) {
84
87
  head += ' re m' + String(m.inReplyTo);
85
88
  }
package/dist/store.js CHANGED
@@ -39,6 +39,7 @@ CREATE TABLE IF NOT EXISTS messages (
39
39
  is_reply INTEGER NOT NULL,
40
40
  in_reply_to INTEGER,
41
41
  verdict TEXT,
42
+ via TEXT,
42
43
  created_at INTEGER NOT NULL,
43
44
  UNIQUE (thread_id, seq)
44
45
  );
@@ -64,6 +65,7 @@ CREATE TABLE IF NOT EXISTS sessions (
64
65
  cwd TEXT,
65
66
  state TEXT,
66
67
  state_at INTEGER,
68
+ pinned INTEGER NOT NULL DEFAULT 0,
67
69
  started_at INTEGER NOT NULL,
68
70
  updated_at INTEGER NOT NULL,
69
71
  UNIQUE (client, cli_session_id)
@@ -78,6 +80,12 @@ CREATE INDEX IF NOT EXISTS idx_deliveries_recipient_state ON deliveries (recipie
78
80
  CREATE INDEX IF NOT EXISTS idx_sessions_handle ON sessions (handle, updated_at, id);
79
81
  CREATE INDEX IF NOT EXISTS idx_sessions_host ON sessions (host_pid, host_start, updated_at, id);
80
82
  `;
83
+ // Columns added after 0.2.1. CREATE TABLE IF NOT EXISTS leaves an older
84
+ // database as it was, so each one is added when PRAGMA table_info lacks it.
85
+ const ADDED_COLUMNS = [
86
+ ['messages', 'via', 'TEXT'],
87
+ ['sessions', 'pinned', 'INTEGER NOT NULL DEFAULT 0'],
88
+ ];
81
89
  // Delivery states that still count as unread for inbox purposes.
82
90
  const UNREAD_STATES_SQL = "('queued','sent','delivered')";
83
91
  function toPeerRow(r) {
@@ -104,6 +112,7 @@ function toSessionRow(r) {
104
112
  cwd: r.cwd,
105
113
  state: r.state,
106
114
  stateAt: r.state_at,
115
+ pinned: r.pinned === 1,
107
116
  startedAt: r.started_at,
108
117
  updatedAt: r.updated_at,
109
118
  };
@@ -122,6 +131,7 @@ function toMessageRow(r) {
122
131
  isReply: r.is_reply === 1,
123
132
  inReplyTo: r.in_reply_to,
124
133
  verdict: r.verdict,
134
+ via: r.via,
125
135
  createdAt: r.created_at,
126
136
  };
127
137
  }
@@ -175,6 +185,16 @@ export class Store {
175
185
  db.pragma('journal_mode = WAL');
176
186
  db.pragma('foreign_keys = ON');
177
187
  db.exec(SCHEMA_SQL);
188
+ // Immediate: take the write lock before the check, so a second process
189
+ // opening the same old database waits instead of hitting a duplicate column.
190
+ db.transaction(() => {
191
+ for (const [table, column, ddl] of ADDED_COLUMNS) {
192
+ const columns = db.prepare('PRAGMA table_info(' + table + ')').all();
193
+ if (!columns.some((c) => c.name === column)) {
194
+ db.exec('ALTER TABLE ' + table + ' ADD COLUMN ' + column + ' ' + ddl);
195
+ }
196
+ }
197
+ }).immediate();
178
198
  // The database holds every message and each session's native messaging
179
199
  // token: owner-only, like the token file.
180
200
  for (const file of [dbPath, dbPath + '-wal', dbPath + '-shm']) {
@@ -217,6 +237,7 @@ export class Store {
217
237
  this.stmt('UPDATE group_members SET handle = ? WHERE handle = ?').run(newHandle, oldHandle);
218
238
  this.stmt('UPDATE deliveries SET recipient = ? WHERE recipient = ?').run(newHandle, oldHandle);
219
239
  this.stmt('UPDATE messages SET sender = ? WHERE sender = ?').run(newHandle, oldHandle);
240
+ this.stmt('UPDATE messages SET via = ? WHERE via = ?').run(newHandle, oldHandle);
220
241
  this.stmt('UPDATE threads SET created_by = ? WHERE created_by = ?').run(newHandle, oldHandle);
221
242
  });
222
243
  move();
@@ -266,8 +287,8 @@ export class Store {
266
287
  const seqRec = this.stmt('SELECT COALESCE(MAX(seq), -1) + 1 AS next_seq FROM messages WHERE thread_id = ?')
267
288
  .get(arg.threadId);
268
289
  const seq = seqRec === undefined ? 0 : seqRec.next_seq;
269
- const info = this.stmt(`INSERT INTO messages (thread_id, seq, sender, body, delivered_body, truncated, refs_json, mode, is_reply, in_reply_to, verdict, created_at)
270
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(arg.threadId, seq, arg.sender, arg.body, arg.deliveredBody, arg.truncated ? 1 : 0, JSON.stringify(arg.refs), arg.mode, arg.isReply ? 1 : 0, arg.inReplyTo, arg.verdict, arg.createdAt);
290
+ const info = this.stmt(`INSERT INTO messages (thread_id, seq, sender, body, delivered_body, truncated, refs_json, mode, is_reply, in_reply_to, verdict, via, created_at)
291
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(arg.threadId, seq, arg.sender, arg.body, arg.deliveredBody, arg.truncated ? 1 : 0, JSON.stringify(arg.refs), arg.mode, arg.isReply ? 1 : 0, arg.inReplyTo, arg.verdict, arg.via, arg.createdAt);
271
292
  return { id: Number(info.lastInsertRowid), seq };
272
293
  }
273
294
  addDeliveries(messageId, recipients, now) {
@@ -461,6 +482,7 @@ export class Store {
461
482
  ['cwd', 'cwd'],
462
483
  ['state', 'state'],
463
484
  ['stateAt', 'state_at'],
485
+ ['pinned', 'pinned'],
464
486
  ['updatedAt', 'updated_at'],
465
487
  ];
466
488
  const sets = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "murmur-it",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Local, client-agnostic message bus for AI CLI sessions with group threads",
5
5
  "license": "MIT",
6
6
  "author": "Renn F",