murmur-it 0.2.1 → 0.2.2
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 +21 -0
- package/README.md +7 -3
- package/adapters/hummin/murmur.ts +1 -1
- package/dist/broker.js +59 -1
- package/dist/cli.js +28 -3
- package/dist/core.js +70 -6
- package/dist/hooks.js +47 -0
- package/dist/mcp.js +5 -4
- package/dist/proof.js +10 -0
- package/dist/protocol.js +4 -1
- package/dist/store.js +24 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,26 @@ All notable changes to murmur are documented here. The format follows
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
5
|
[Semantic Versioning](https://semver.org/).
|
|
6
6
|
|
|
7
|
+
## [0.2.2] - 2026-10-20
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- `/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.
|
|
12
|
+
- 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.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- 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.
|
|
17
|
+
- `via` on messages, thread views, `MessageSummary` and `SendResult`, backed by a nullable `messages.via` column.
|
|
18
|
+
- `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.
|
|
19
|
+
- Schema migration: `messages.via` and `sessions.pinned` are added to an existing database when `PRAGMA table_info` lacks them.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- Handles may be up to 48 characters (`^[a-z0-9][a-z0-9-]{1,47}$`), up from 32, so title slugs fit.
|
|
24
|
+
- 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.
|
|
25
|
+
- Hummin's model-free `/murmur` passes its process as the ancestor, so its messages carry the session as `via`.
|
|
26
|
+
|
|
7
27
|
## [0.2.1] - 2026-10-20
|
|
8
28
|
|
|
9
29
|
### Fixed
|
|
@@ -61,6 +81,7 @@ All notable changes to murmur are documented here. The format follows
|
|
|
61
81
|
- Limits: send rate, duplicate window, thread and inbox caps.
|
|
62
82
|
- 283 tests at 100 percent lines and branches, and an end-to-end rig that replayed the live 3-peer scenario.
|
|
63
83
|
|
|
84
|
+
[0.2.2]: https://github.com/rennf93/murmur/releases/tag/v0.2.2
|
|
64
85
|
[0.2.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1
|
|
65
86
|
[0.2.1-rc.1]: https://github.com/rennf93/murmur/releases/tag/v0.2.1-rc.1
|
|
66
87
|
[0.2.0]: https://github.com/rennf93/murmur/releases/tag/v0.2.0
|
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
<img src="docs/assets/murmur-512.png" alt="murmur" width="96">
|
|
2
|
+
|
|
1
3
|
# murmur
|
|
2
4
|
|
|
3
5
|
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.
|
|
@@ -38,7 +40,9 @@ Every hook, MCP server and CLI command walks up its process ancestors and takes
|
|
|
38
40
|
- 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
41
|
- 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
42
|
- 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
|
|
43
|
+
- `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`.
|
|
44
|
+
- 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.
|
|
45
|
+
- Handles are 1 to 48 characters: `^[a-z0-9][a-z0-9-]{1,47}$`.
|
|
42
46
|
|
|
43
47
|
## Delivery truth table
|
|
44
48
|
|
|
@@ -66,7 +70,7 @@ What a session sees for every message, on every path:
|
|
|
66
70
|
## Threads, groups, verdicts
|
|
67
71
|
|
|
68
72
|
- 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
|
|
73
|
+
- Replies go to everyone in the thread (every sender, every recipient and every session an owner message was typed in, so far), in the parent's mode, so peers see each other's answers without relaying. To consult several sessions, send once to all of them.
|
|
70
74
|
- 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
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).
|
|
72
76
|
- `references` carries pointers (paths, commits, URLs) so artifacts stay in their repos.
|
|
@@ -81,7 +85,7 @@ The human surface, as the owner:
|
|
|
81
85
|
- `/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
86
|
- `murmur send <targets> <body...> [--mode push|notify|silent] [--refs a,b] [--thread <id>] [--as <handle>]`
|
|
83
87
|
- `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
|
|
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)
|
|
85
89
|
|
|
86
90
|
## Doctrine
|
|
87
91
|
|
|
@@ -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)}`;
|
package/dist/broker.js
CHANGED
|
@@ -220,6 +220,7 @@ export class Broker {
|
|
|
220
220
|
reader: new LineReader(),
|
|
221
221
|
authenticated: false,
|
|
222
222
|
handle: null,
|
|
223
|
+
via: null,
|
|
223
224
|
live: false,
|
|
224
225
|
listening: false,
|
|
225
226
|
pendingHost: null,
|
|
@@ -403,6 +404,9 @@ export class Broker {
|
|
|
403
404
|
case 'status':
|
|
404
405
|
this.replyOk(conn.socket, id, this.handleStatus());
|
|
405
406
|
return;
|
|
407
|
+
case 'prune':
|
|
408
|
+
this.replyOk(conn.socket, id, this.handlePrune());
|
|
409
|
+
return;
|
|
406
410
|
case 'fetch-push':
|
|
407
411
|
this.replyOk(conn.socket, id, this.handleFetchPush(rec));
|
|
408
412
|
return;
|
|
@@ -424,8 +428,12 @@ export class Broker {
|
|
|
424
428
|
const owner = optBool(rec, 'owner') === true;
|
|
425
429
|
const live = kind === 'mcp' || kind === 'adapter';
|
|
426
430
|
let resolved;
|
|
431
|
+
conn.via = null;
|
|
427
432
|
if (owner) {
|
|
428
433
|
resolved = this.ownerHandle();
|
|
434
|
+
if (ancestors !== undefined) {
|
|
435
|
+
conn.via = this.core.sessionForAncestors(ancestors)?.handle ?? null;
|
|
436
|
+
}
|
|
429
437
|
}
|
|
430
438
|
else if (host !== undefined) {
|
|
431
439
|
const session = this.core.sessionForHost(host);
|
|
@@ -439,6 +447,7 @@ export class Broker {
|
|
|
439
447
|
return { handle: '', owner: false };
|
|
440
448
|
}
|
|
441
449
|
resolved = handle === undefined ? session.handle : this.core.renameSession(session, handle);
|
|
450
|
+
this.rebind(session.handle, resolved);
|
|
442
451
|
}
|
|
443
452
|
else if (ancestors !== undefined && handle === undefined) {
|
|
444
453
|
resolved = this.core.sessionForAncestors(ancestors)?.handle ?? this.ownerHandle();
|
|
@@ -482,6 +491,7 @@ export class Broker {
|
|
|
482
491
|
const transcriptPath = optString(rec, 'transcriptPath');
|
|
483
492
|
const cwd = optString(rec, 'cwd');
|
|
484
493
|
const handle = optString(rec, 'handle');
|
|
494
|
+
const title = optString(rec, 'title');
|
|
485
495
|
const listen = optBool(rec, 'listen') === true;
|
|
486
496
|
let native;
|
|
487
497
|
if (rec.native !== undefined) {
|
|
@@ -491,6 +501,8 @@ export class Broker {
|
|
|
491
501
|
const nat = rec.native;
|
|
492
502
|
native = { socketPath: reqString(nat, 'socketPath'), token: reqString(nat, 'token') };
|
|
493
503
|
}
|
|
504
|
+
// A title can rename the session, so find the name it had before.
|
|
505
|
+
const before = (cliSessionId === null ? null : this.store.sessionByCliId(client, cliSessionId)) ?? this.store.sessionByHost(host.hostPid, host.hostStart);
|
|
494
506
|
const session = this.core.sessionEvent({
|
|
495
507
|
event,
|
|
496
508
|
client,
|
|
@@ -498,9 +510,13 @@ export class Broker {
|
|
|
498
510
|
host,
|
|
499
511
|
...(transcriptPath !== undefined ? { transcriptPath } : {}),
|
|
500
512
|
...(cwd !== undefined ? { cwd } : {}),
|
|
513
|
+
...(title !== undefined ? { title } : {}),
|
|
501
514
|
...(handle !== undefined ? { handle } : {}),
|
|
502
515
|
...(native !== undefined ? { native } : {}),
|
|
503
516
|
});
|
|
517
|
+
if (before !== null) {
|
|
518
|
+
this.rebind(before.handle, session.handle);
|
|
519
|
+
}
|
|
504
520
|
conn.listening = listen;
|
|
505
521
|
this.bind(conn, session.handle, listen);
|
|
506
522
|
// MCP servers of this session that registered before it announced itself.
|
|
@@ -551,6 +567,7 @@ export class Broker {
|
|
|
551
567
|
threadId,
|
|
552
568
|
to,
|
|
553
569
|
body,
|
|
570
|
+
via: conn.via,
|
|
554
571
|
};
|
|
555
572
|
if (references !== undefined) {
|
|
556
573
|
arg.references = references;
|
|
@@ -584,7 +601,11 @@ export class Broker {
|
|
|
584
601
|
const body = reqString(rec, 'body');
|
|
585
602
|
const verdict = optEnum(rec, 'verdict', VERDICTS);
|
|
586
603
|
const references = optStringArray(rec, 'references');
|
|
587
|
-
const arg = {
|
|
604
|
+
const arg = {
|
|
605
|
+
messageId,
|
|
606
|
+
body,
|
|
607
|
+
via: conn.via,
|
|
608
|
+
};
|
|
588
609
|
if (verdict !== undefined) {
|
|
589
610
|
arg.verdict = verdict;
|
|
590
611
|
}
|
|
@@ -671,6 +692,17 @@ export class Broker {
|
|
|
671
692
|
handleStatus() {
|
|
672
693
|
return this.core.status((handle) => ({ online: this.presence.has(handle) }));
|
|
673
694
|
}
|
|
695
|
+
// Every handle with a connection, so a peer someone is talking through is
|
|
696
|
+
// never pruned.
|
|
697
|
+
handlePrune() {
|
|
698
|
+
const connected = new Set();
|
|
699
|
+
for (const conn of this.conns) {
|
|
700
|
+
if (conn.handle !== null) {
|
|
701
|
+
connected.add(conn.handle);
|
|
702
|
+
}
|
|
703
|
+
}
|
|
704
|
+
return { removed: this.core.prune(connected) };
|
|
705
|
+
}
|
|
674
706
|
handleFetchPush(rec) {
|
|
675
707
|
const handle = reqString(rec, 'handle');
|
|
676
708
|
const limit = reqNumber(rec, 'limit');
|
|
@@ -999,6 +1031,32 @@ export class Broker {
|
|
|
999
1031
|
this.presence.set(handle, conn);
|
|
1000
1032
|
}
|
|
1001
1033
|
}
|
|
1034
|
+
// A session's name changed: connections still bound to the old one (its MCP
|
|
1035
|
+
// server, an adapter) follow it, unless another live session still holds
|
|
1036
|
+
// it. Ended sessions left on the old name do not count.
|
|
1037
|
+
rebind(from, to) {
|
|
1038
|
+
if (from === to || !this.core.claimable(from, null)) {
|
|
1039
|
+
return;
|
|
1040
|
+
}
|
|
1041
|
+
for (const conn of this.conns) {
|
|
1042
|
+
if (conn.handle === from) {
|
|
1043
|
+
this.bind(conn, to, conn.live);
|
|
1044
|
+
}
|
|
1045
|
+
}
|
|
1046
|
+
// A whole-identity rename moved the deliveries; pending proof and
|
|
1047
|
+
// batched notifications follow them.
|
|
1048
|
+
if (this.store.getPeer(from) === null) {
|
|
1049
|
+
this.proof.rename(from, to);
|
|
1050
|
+
const entry = this.notifyQueue.get(from);
|
|
1051
|
+
if (entry !== undefined) {
|
|
1052
|
+
clearTimeout(entry.timer);
|
|
1053
|
+
this.notifyQueue.delete(from);
|
|
1054
|
+
for (const payload of entry.payloads) {
|
|
1055
|
+
this.enqueueNotification(to, payload);
|
|
1056
|
+
}
|
|
1057
|
+
}
|
|
1058
|
+
}
|
|
1059
|
+
}
|
|
1002
1060
|
requireBoundHandle(conn) {
|
|
1003
1061
|
if (conn.handle === null && conn.pendingHost !== null) {
|
|
1004
1062
|
const { host, client, cwd } = conn.pendingHost;
|
package/dist/cli.js
CHANGED
|
@@ -13,7 +13,7 @@ const REPLY_USAGE = 'usage: murmur reply <message id> <body...> [--as <handle>]
|
|
|
13
13
|
const NAME_USAGE = 'usage: murmur name <handle> (renames the agent session this runs in)';
|
|
14
14
|
const THREAD_USAGE = 'usage: murmur thread <id> [--since <n>] [--full]';
|
|
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,7 +92,8 @@ 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
|
|
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
98
|
' thread <id> [--since <n>] [--full]',
|
|
96
99
|
' groups [list] | groups create <name> | groups add <name> <members...>',
|
|
@@ -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 {
|
|
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,6 +411,22 @@ 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;
|
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
|
}
|
|
@@ -226,6 +237,7 @@ export class MurmurCore {
|
|
|
226
237
|
isReply: false,
|
|
227
238
|
inReplyTo: null,
|
|
228
239
|
verdict: null,
|
|
240
|
+
via: arg.via ?? null,
|
|
229
241
|
createdAt: ts,
|
|
230
242
|
});
|
|
231
243
|
this.store.addDeliveries(appended.id, recipients, ts);
|
|
@@ -236,7 +248,7 @@ export class MurmurCore {
|
|
|
236
248
|
}
|
|
237
249
|
const deliveries = this.store.getDeliveries(appended.id).map(deliveryInfoOf);
|
|
238
250
|
return {
|
|
239
|
-
result: { messageId: appended.id, threadId, seq: appended.seq, deliveries },
|
|
251
|
+
result: { messageId: appended.id, threadId, seq: appended.seq, via: row.via, deliveries },
|
|
240
252
|
pushes: this.pushesFor(row, recipients, mode),
|
|
241
253
|
};
|
|
242
254
|
}
|
|
@@ -265,8 +277,8 @@ export class MurmurCore {
|
|
|
265
277
|
}
|
|
266
278
|
return this.store.getNativeTransport(recipient) !== null ? 'native' : 'connection';
|
|
267
279
|
}
|
|
268
|
-
// A reply reaches everyone in the thread (every sender
|
|
269
|
-
//
|
|
280
|
+
// A reply reaches everyone in the thread (every sender, every recipient and
|
|
281
|
+
// every session an owner message was typed in, minus the replier) in the parent's delivery mode, so peers see
|
|
270
282
|
// each other's answers without anyone relaying them.
|
|
271
283
|
reply(sender, arg) {
|
|
272
284
|
if (arg.verdict !== undefined && !VERDICTS.includes(arg.verdict)) {
|
|
@@ -279,6 +291,9 @@ export class MurmurCore {
|
|
|
279
291
|
const participants = new Set(this.store.threadRecipientHandles(parent.threadId));
|
|
280
292
|
for (const row of this.store.threadMessages(parent.threadId, null)) {
|
|
281
293
|
participants.add(row.sender);
|
|
294
|
+
if (row.via !== null) {
|
|
295
|
+
participants.add(row.via);
|
|
296
|
+
}
|
|
282
297
|
}
|
|
283
298
|
participants.delete(sender);
|
|
284
299
|
const recipients = [...participants].filter((handle) => this.store.getPeer(handle) !== null);
|
|
@@ -297,6 +312,7 @@ export class MurmurCore {
|
|
|
297
312
|
isReply: true,
|
|
298
313
|
inReplyTo: parent.id,
|
|
299
314
|
verdict: arg.verdict ?? null,
|
|
315
|
+
via: arg.via ?? null,
|
|
300
316
|
createdAt: ts,
|
|
301
317
|
});
|
|
302
318
|
// The sender's own delivery row on the parent message closes the loop:
|
|
@@ -609,7 +625,13 @@ export class MurmurCore {
|
|
|
609
625
|
let row = arg.cliSessionId === null ? null : this.store.sessionByCliId(arg.client, arg.cliSessionId);
|
|
610
626
|
row ??= this.store.sessionByHost(arg.host.hostPid, arg.host.hostStart);
|
|
611
627
|
if (row === null) {
|
|
612
|
-
const
|
|
628
|
+
const explicit = arg.handle !== undefined && this.claimable(arg.handle, null);
|
|
629
|
+
const slug = arg.title === undefined ? '' : slugify(arg.title);
|
|
630
|
+
const handle = explicit
|
|
631
|
+
? arg.handle
|
|
632
|
+
: this.claimable(slug, null)
|
|
633
|
+
? slug
|
|
634
|
+
: this.allocateHandle(arg.client, arg.cwd);
|
|
613
635
|
this.ensurePeer(handle);
|
|
614
636
|
const id = this.store.insertSession({
|
|
615
637
|
client: arg.client,
|
|
@@ -622,6 +644,9 @@ export class MurmurCore {
|
|
|
622
644
|
now: ts,
|
|
623
645
|
});
|
|
624
646
|
row = this.store.sessionById(id);
|
|
647
|
+
if (explicit) {
|
|
648
|
+
this.store.updateSession(id, { pinned: 1 });
|
|
649
|
+
}
|
|
625
650
|
}
|
|
626
651
|
else {
|
|
627
652
|
this.store.updateSession(row.id, {
|
|
@@ -639,7 +664,10 @@ export class MurmurCore {
|
|
|
639
664
|
}
|
|
640
665
|
const state = arg.event === 'prompt' ? 'busy' : arg.event === 'session-end' ? 'ended' : 'idle';
|
|
641
666
|
this.store.updateSession(row.id, { state, stateAt: ts });
|
|
642
|
-
|
|
667
|
+
let fresh = this.store.sessionById(row.id);
|
|
668
|
+
if (arg.title !== undefined) {
|
|
669
|
+
fresh = this.followTitle(fresh, arg.title);
|
|
670
|
+
}
|
|
643
671
|
if (arg.native !== undefined) {
|
|
644
672
|
this.store.upsertNativeTransport(fresh.handle, arg.native.socketPath, arg.native.token, ts);
|
|
645
673
|
}
|
|
@@ -648,6 +676,19 @@ export class MurmurCore {
|
|
|
648
676
|
}
|
|
649
677
|
return fresh;
|
|
650
678
|
}
|
|
679
|
+
// The session shows its CLI title as its display name, and takes the title's
|
|
680
|
+
// slug as its handle while the handle is automatic (not pinned by an explicit
|
|
681
|
+
// name) and no other live session holds the slug.
|
|
682
|
+
followTitle(row, title) {
|
|
683
|
+
let current = row;
|
|
684
|
+
const slug = slugify(title);
|
|
685
|
+
if (!row.pinned && slug !== row.handle && this.claimable(slug, row.id)) {
|
|
686
|
+
this.moveSession(row, slug);
|
|
687
|
+
current = this.store.sessionById(row.id);
|
|
688
|
+
}
|
|
689
|
+
this.store.upsertPeer(current.handle, title, null, false, this.nowMs());
|
|
690
|
+
return current;
|
|
691
|
+
}
|
|
651
692
|
// The session running under this exact host process, if one announced
|
|
652
693
|
// itself. With create, a missing session is made on the spot (an MCP
|
|
653
694
|
// server whose hooks never ran still gets an identity).
|
|
@@ -677,8 +718,14 @@ export class MurmurCore {
|
|
|
677
718
|
// Gives the session a new name. A free name renames the identity with all
|
|
678
719
|
// its history; a name held by a peer with no live session is taken over
|
|
679
720
|
// (the session joins that identity, its groups and inbox); a live or
|
|
680
|
-
// owner handle is refused.
|
|
721
|
+
// owner handle is refused. An explicit name pins the handle against the
|
|
722
|
+
// CLI's title.
|
|
681
723
|
renameSession(row, handle) {
|
|
724
|
+
const named = this.moveSession(row, handle);
|
|
725
|
+
this.store.updateSession(row.id, { pinned: 1 });
|
|
726
|
+
return named;
|
|
727
|
+
}
|
|
728
|
+
moveSession(row, handle) {
|
|
682
729
|
if (!HANDLE_RE.test(handle)) {
|
|
683
730
|
throw new MurmurError('bad_request', 'invalid handle: ' + handle);
|
|
684
731
|
}
|
|
@@ -699,6 +746,23 @@ export class MurmurCore {
|
|
|
699
746
|
}
|
|
700
747
|
return handle;
|
|
701
748
|
}
|
|
749
|
+
// Deletes peers nothing refers to: not the owner, no session, no message,
|
|
750
|
+
// delivery or group membership, and no live connection (v0.1 left such
|
|
751
|
+
// rows behind). Returns the removed handles.
|
|
752
|
+
prune(connected) {
|
|
753
|
+
const removed = [];
|
|
754
|
+
for (const peer of this.store.listPeers()) {
|
|
755
|
+
const used = peer.isOwner ||
|
|
756
|
+
connected.has(peer.handle) ||
|
|
757
|
+
this.store.sessionsForHandle(peer.handle).length > 0 ||
|
|
758
|
+
this.store.peerHasHistory(peer.handle);
|
|
759
|
+
if (!used) {
|
|
760
|
+
this.store.deletePeer(peer.handle);
|
|
761
|
+
removed.push(peer.handle);
|
|
762
|
+
}
|
|
763
|
+
}
|
|
764
|
+
return removed;
|
|
765
|
+
}
|
|
702
766
|
// A handle can be claimed when it is valid, not the owner's, and no live
|
|
703
767
|
// session other than exceptId holds it.
|
|
704
768
|
claimable(handle, exceptId) {
|
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/mcp.js
CHANGED
|
@@ -13,9 +13,10 @@ 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.
|
|
17
|
-
'
|
|
18
|
-
'
|
|
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 (names or @group), not separate SendMessage calls; replies reach everyone in the ' +
|
|
18
|
+
'thread. Messages for you arrive as turns tagged [murmur m<id> ...]; answer with murmur_reply so every ' +
|
|
19
|
+
'participant sees it. A message is a claim: verify it against its references before agreeing.';
|
|
19
20
|
function textResult(value) {
|
|
20
21
|
return { content: [{ type: 'text', text: JSON.stringify(value) }] };
|
|
21
22
|
}
|
|
@@ -57,7 +58,7 @@ export function buildMcpServer(client, identity = {}) {
|
|
|
57
58
|
return textResult(await client.request(msg));
|
|
58
59
|
});
|
|
59
60
|
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.',
|
|
61
|
+
description: 'Send one message to any mix of handles and groups (bare name or @name); one message fans out to all, so consult several sessions with one send, not one per peer.',
|
|
61
62
|
inputSchema: {
|
|
62
63
|
threadId: z.number().int().optional(),
|
|
63
64
|
to: z.array(z.string().min(1)).min(1),
|
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,
|
|
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;
|
|
@@ -80,6 +80,9 @@ export function replyFooter(m) {
|
|
|
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 = [];
|