brane 0.0.2 → 0.3.0

package/dist/test/mentions-e2e.test.js

@@ -0,0 +1,261 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { startMcpListen, handleMcpNarrate, createMentionRecorder, wakeListenWaiters, } from "../daemon/server.js";
+import { appendEvent } from "../db/events.js";
+import { allMentions, pendingMentions } from "../db/mentions.js";
+// The flows an agent actually runs, end to end through the real pieces: the
+// real markdown scan (so a handle in a fence is inert here for the same reason
+// it is inert on screen), the real recorder with its guards, the real wake
+// path, the real receipt.
+//
+// The other mention suites test parts. This one tests that the parts are wired
+// to each other — which is where a feature like this dies.
+const A = "claude-aaaaaaaa"; // the one doing the mentioning
+const B = "claude-bbbbbbbb"; // the one being mentioned
+const C = "goose-cccccccc"; // a third narrative
+const BRANE = "brane-home";
+/** A whole brane: a db, the real recorder, and a wake fabric. */
+function brane() {
+    const db = createTestDb();
+    const ins = db.prepare("INSERT INTO narratives (id, brane_id, created_at, status) VALUES (?, ?, 0, 'active')");
+    for (const nid of [A, B, C])
+        ins.run(nid, BRANE);
+    const listenWaiters = new Map();
+    const notify = (nid) => wakeListenWaiters(listenWaiters, nid);
+    const record = createMentionRecorder(db, notify);
+    /** An agent with a bridge whose socket records what it was sent. */
+    function agent(nid) {
+        const sent = [];
+        const client = {
+            ws: {
+                readyState: 1,
+                send: (raw) => {
+                    const msg = JSON.parse(raw);
+                    if (msg.type === "tool_result")
+                        sent.push({ callId: msg.id, result: msg.result });
+                },
+            },
+            narrativeId: nid,
+            agentType: "claude",
+            pendingListens: new Map(),
+        };
+        let calls = 0;
+        return {
+            nid,
+            sent,
+            client,
+            /** Park on `listen`, or resolve immediately if something is waiting. */
+            listen(args = {}) {
+                startMcpListen(client, db, `${nid}-${++calls}`, { after: { self: 0 }, ...args }, listenWaiters, () => { }, BRANE);
+            },
+            /** Say something — into this narrative, or into another's. */
+            say(text, into) {
+                return handleMcpNarrate({ say: text, ...(into ? { nid: into } : {}) }, db, nid, notify, undefined, record, BRANE);
+            },
+            last() {
+                return sent[sent.length - 1]?.result;
+            },
+        };
+    }
+    /** The operator typing into a narrative's composer. */
+    function operatorSignal(into, text) {
+        const event = appendEvent(db, into, "human_signal", { content: text, source: "web" });
+        notify(into);
+        record(into, event, "web");
+    }
+    return { db, agent, operatorSignal, notify };
+}
+describe("one agent gets another's attention", () => {
+    it("wakes a parked listen and hands over a pointer to the message", () => {
+        const { agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        b.listen(); // B is idle, blocked on listen
+        assert.equal(b.sent.length, 0);
+        assert.equal(b.client.pendingListens.size, 1);
+        a.say(`found the bug in the resync path, @${B} — it's the rAF guard`);
+        assert.equal(b.sent.length, 1, "the mention must wake B");
+        assert.equal(b.client.pendingListens.size, 0);
+        const m = b.last().mentions;
+        assert.equal(m.length, 1);
+        assert.equal(m[0].src, A, "where to go read");
+        assert.equal(m[0].author, A, "who said it");
+        assert.equal(m[0].seq, 1);
+        assert.equal(b.last().events.self.length, 0, "nothing landed in B's own log");
+    });
+    it("B reads A, which settles it, and B answers into A's narrative", () => {
+        const { db, agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        b.listen();
+        a.say(`@${B} can you take the ledger tests?`);
+        const { src, seq } = b.last().mentions[0];
+        // Interpreting a mention means going to read it. The cursor is the ack.
+        b.listen({ after: { self: 0, [src]: seq - 1 } });
+        const events = b.last().events[src];
+        assert.equal(events.length, 1);
+        assert.deepEqual(events[0].mentions, [B], "the event says it addresses B");
+        assert.equal(pendingMentions(db, B, 10).total, 0, "reading it settled it");
+        // B replies the loud way — into A's narrative.
+        b.say("on it", A);
+        const aEvents = db.prepare("SELECT type, source FROM events WHERE narrative_id = ?").all(A);
+        assert.deepEqual(aEvents.map((e) => e.type), ["narration", "agent_signal"]);
+        // And B goes back to idle without being re-woken by the settled mention.
+        b.listen();
+        assert.equal(b.client.pendingListens.size, 1, "B parks again");
+    });
+    it("an unread mention nags but does not re-wake", () => {
+        const { agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        b.listen();
+        a.say(`@${B} low priority, whenever`);
+        assert.equal(b.sent.length, 1);
+        // B parks and re-parks without reading A. It is reminded on each *resolved*
+        // call, but the unread mention never resolves one by itself again.
+        for (let i = 0; i < 5; i++)
+            b.listen();
+        assert.equal(b.sent.length, 1, "SPIN LOOP: an unread mention re-resolved a listen");
+        // A fresh mention does wake it, and the unread one rides along.
+        b.listen();
+        a.say(`@${B} bumping this`);
+        assert.equal(b.sent.length, 2);
+        assert.equal(b.last().mentions.length, 2, "both are still owed");
+    });
+});
+describe("mentioning an agent that isn't running", () => {
+    it("records without waking anything, and delivers when it comes back", () => {
+        const { db, agent } = brane();
+        const a = agent(A);
+        // B has no bridge at all — nothing is listening.
+        a.say(`@${B} when you're back, the migration needs a look`);
+        assert.equal(pendingMentions(db, B, 10).total, 1);
+        assert.equal(db.prepare("SELECT COUNT(*) c FROM events WHERE narrative_id = ?").get(B).c, 0, "and nothing was written into B's log — no revive, no trace");
+        // B restarts and does what a restarted agent does: whoami, then listen.
+        const b = agent(B);
+        const recovered = allMentions(db, B, 10, BRANE);
+        assert.equal(recovered.length, 1);
+        assert.equal(recovered[0].src, A);
+        b.listen();
+        assert.equal(b.sent.length, 1, "the first listen after a restart delivers it");
+        assert.equal(b.last().mentions[0].src, A);
+    });
+    it("survives a restart that loses the agent's cursor entirely", () => {
+        const { db, agent } = brane();
+        agent(A).say(`@${B} ping`);
+        // A restarted agent re-derives its cursor from tail:50 and may well read
+        // from 0. The mention must not be lost to that, nor re-delivered forever.
+        const b = agent(B);
+        b.listen({ tail: { self: 50 } });
+        assert.equal(b.sent.length, 1);
+        assert.equal(b.last().mentions.length, 1);
+        b.listen({ after: { self: 0 } });
+        assert.equal(b.sent.length, 1, "a rewound cursor must not resurrect the wake");
+        assert.equal(pendingMentions(db, B, 10).total, 1, "but it is still owed until read");
+    });
+});
+describe("the operator mentions an agent", () => {
+    it("delivers a human signal's mention the same way", () => {
+        const { agent, operatorSignal } = brane();
+        const b = agent(B);
+        b.listen();
+        // Typed into A's composer: "@B — look at this".
+        operatorSignal(A, `@${B} see the trace above`);
+        assert.equal(b.sent.length, 1);
+        assert.equal(b.last().mentions[0].author, "web", "the operator, not an agent");
+        assert.equal(b.last().mentions[0].src, A);
+    });
+});
+describe("a third party's narration", () => {
+    it("names where to read and who said it, separately", () => {
+        const { agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        b.listen();
+        // A narrates into C's narrative, mentioning B. B must be sent to C to read
+        // it, while knowing A wrote it.
+        a.say(`@${B} this is the thread`, C);
+        const m = b.last().mentions[0];
+        assert.equal(m.src, C, "read C");
+        assert.equal(m.author, A, "A said it");
+    });
+});
+describe("what must not page anyone", () => {
+    it("a handle inside a fenced block in a real narration", () => {
+        const { db, agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        b.listen();
+        a.say(`here's the log I was sent:\n\n\`\`\`\n[12:03] operator: ping @${B}\n\`\`\`\n\nnot sure what to make of it`);
+        assert.equal(b.sent.length, 0, "a pasted log must not page anyone");
+        assert.equal(b.client.pendingListens.size, 1);
+        assert.equal(pendingMentions(db, B, 10).total, 0);
+    });
+    it("a handle in a code span, a link, or mid-word", () => {
+        const { db, agent } = brane();
+        const a = agent(A);
+        a.say(`run \`brane revive @${B}\` — see [@${B}](https://example.com/x) or mail ben@${B}`);
+        assert.equal(pendingMentions(db, B, 10).total, 0);
+    });
+    it("an agent mentioning itself", () => {
+        const { db, agent } = brane();
+        const b = agent(B);
+        b.say(`note to self: @${B} should check this`);
+        assert.equal(pendingMentions(db, B, 10).total, 0);
+    });
+    it("an author mentioning itself in someone else's narrative", () => {
+        const { db, agent } = brane();
+        // A narrates into B and signs off `@A`. The words are A's own; a row would
+        // wake A's own `narrate({ wait })` at once, pointing at an event A's cursor
+        // never reads, so the reminder would recur until dismissed.
+        agent(A).say(`answered — ping @${A} if not`, B);
+        assert.equal(pendingMentions(db, A, 10).total, 0);
+    });
+    it("a mention of the narrative being narrated into", () => {
+        const { db, agent } = brane();
+        // A narrates into B's narrative and mentions B. The message is already in
+        // B's log and already woke it; a row would be a duplicate plus a wake.
+        agent(A).say(`@${B} here you go`, B);
+        assert.equal(pendingMentions(db, B, 10).total, 0);
+        assert.equal(db.prepare("SELECT COUNT(*) c FROM events WHERE narrative_id = ?").get(B).c, 1, "the agent_signal itself still landed");
+    });
+    it("a handle that names no narrative", () => {
+        const { db, agent } = brane();
+        agent(A).say("@claude-deadbeef are you there?");
+        assert.equal(db.prepare("SELECT COUNT(*) c FROM mentions").get().c, 0);
+    });
+});
+describe("the loop stays exactly as it was when no one is mentioned", () => {
+    it("an ordinary narrate/listen exchange is byte-identical", () => {
+        const { agent, operatorSignal } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        const narrated = a.say("working on the resync heartbeat");
+        assert.equal("mentions" in narrated, false);
+        assert.equal("mentions_pending" in narrated, false);
+        b.listen();
+        operatorSignal(B, "how's it going?");
+        assert.equal(b.sent.length, 1);
+        assert.deepEqual(Object.keys(b.last()).sort(), ["events", "timed_out", "waited_ms"]);
+    });
+});
+describe("two agents mentioning each other", () => {
+    it("each wake is earned by a new mention, never by an old one", () => {
+        const { agent } = brane();
+        const a = agent(A);
+        const b = agent(B);
+        // The shape that would ping-pong if an unread mention could re-resolve.
+        for (let round = 0; round < 5; round++) {
+            a.listen();
+            b.listen();
+            a.say(`round ${round} @${B}`);
+            b.say(`round ${round} @${A}`);
+        }
+        // Five mentions each way, five wakes each way — one per new mention, and
+        // never a sixth from the pile of unread ones.
+        assert.equal(a.sent.length, 5);
+        assert.equal(b.sent.length, 5);
+    });
+});
+//# sourceMappingURL=mentions-e2e.test.js.map

package/dist/test/mentions-ledger.test.js

@@ -0,0 +1,265 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { recordMentions, pendingMentions, allMentions, hasUnsentMentions, ackMentionsByRead, dismissMentions, markSent, mentionsInEvents, } from "../db/mentions.js";
+// The ledger makes two guarantees survive restarts, crashes and re-scans: a
+// mention wakes an agent exactly once, and a mention the agent never actually
+// read keeps coming back. Those pull in opposite directions, which is why each
+// row carries two marks — `sent_at` for the first, `seen_at` for the second.
+// Most of what follows pins that split, and one test pins the reason they are
+// per-row rather than high-water marks per narrative.
+const A = "claude-aaaaaaaa";
+const B = "claude-bbbbbbbb";
+const C = "goose-cccccccc";
+function db() {
+    const d = createTestDb();
+    const ins = d.prepare("INSERT INTO narratives (id, brane_id, created_at, status) VALUES (?, ?, 0, 'active')");
+    ins.run(A, "brane-home");
+    ins.run(B, "brane-home");
+    ins.run(C, "brane-far");
+    return d;
+}
+/** B mentions A at `seq`. */
+function mention(d, seq, src = B, mentioned = A) {
+    return recordMentions(d, {
+        mentionedNids: [mentioned],
+        srcNarrative: src,
+        srcSeq: seq,
+        author: src,
+        time: 1000 + seq,
+    });
+}
+describe("recording", () => {
+    it("returns the rising edge, so only new mentions wake anyone", () => {
+        const d = db();
+        assert.deepEqual(mention(d, 5), [A]);
+        assert.deepEqual(mention(d, 5), [], "a re-scan of the same event wakes nobody");
+        assert.deepEqual(mention(d, 6), [A]);
+    });
+    it("dedups a handle repeated inside one event", () => {
+        const d = db();
+        const fresh = recordMentions(d, {
+            mentionedNids: [A, A, C],
+            srcNarrative: B,
+            srcSeq: 1,
+            author: B,
+            time: 1,
+        });
+        assert.deepEqual(fresh, [A, C]);
+        const { c } = d.prepare("SELECT COUNT(*) c FROM mentions").get();
+        assert.equal(c, 2);
+    });
+    it("is idempotent under a full re-scan, which is what makes rebuild safe", () => {
+        const d = db();
+        for (const seq of [1, 2, 3])
+            mention(d, seq);
+        markSent(d, A);
+        const before = d.prepare("SELECT id, src_seq, sent_at FROM mentions ORDER BY id").all();
+        for (const seq of [1, 2, 3])
+            mention(d, seq);
+        const after = d.prepare("SELECT id, src_seq, sent_at FROM mentions ORDER BY id").all();
+        // Same rows, same ids, and — the part that matters — delivery state
+        // untouched. A rebuild that reassigned ids or cleared these would
+        // re-deliver mentions the agent already handled.
+        assert.deepEqual(after, before);
+    });
+    it("keeps mentions of different narratives apart", () => {
+        const d = db();
+        recordMentions(d, { mentionedNids: [A, C], srcNarrative: B, srcSeq: 1, author: B, time: 1 });
+        assert.equal(pendingMentions(d, A, 10).total, 1);
+        assert.equal(pendingMentions(d, C, 10).total, 1);
+        assert.equal(pendingMentions(d, B, 10).total, 0);
+    });
+});
+describe("the two marks", () => {
+    it("delivery stops the wake but not the reminder", () => {
+        const d = db();
+        mention(d, 5);
+        assert.ok(hasUnsentMentions(d, A), "undelivered: should wake");
+        const { rows } = pendingMentions(d, A, 10);
+        markSent(d, A); // what delivery does
+        assert.equal(hasUnsentMentions(d, A), false, "delivered: must not wake again");
+        assert.equal(pendingMentions(d, A, 10).total, 1, "unread: must still be shown");
+        assert.equal(rows[0].src, B);
+    });
+    it("a new mention wakes again even while an old one is still unread", () => {
+        const d = db();
+        mention(d, 5);
+        markSent(d, A);
+        assert.equal(hasUnsentMentions(d, A), false);
+        mention(d, 6);
+        assert.ok(hasUnsentMentions(d, A));
+        assert.equal(pendingMentions(d, A, 10).total, 2);
+    });
+    it("neither mark can rewind, because there is no value that would", () => {
+        // A high-water integer can be written backwards by a cursor that reset.
+        // NULL -> timestamp cannot: re-running either transition is a no-op.
+        const d = db();
+        for (const seq of [1, 2, 3])
+            mention(d, seq);
+        markSent(d, A);
+        markSent(d, A);
+        assert.equal(hasUnsentMentions(d, A), false);
+        ackMentionsByRead(d, A, { [B]: [1, 2, 3, 5] });
+        ackMentionsByRead(d, A, { [B]: [1, 2, 3, 5] });
+        assert.equal(pendingMentions(d, A, 10).total, 0);
+    });
+    it("caps the receipt without leaving a remainder that re-wakes", () => {
+        const d = db();
+        for (let seq = 1; seq <= 25; seq++)
+            mention(d, seq);
+        const { rows, total } = pendingMentions(d, A, 10);
+        assert.equal(rows.length, 10);
+        assert.equal(total, 25);
+        // markSent covers everything pending, not just the slice shown.
+        markSent(d, A);
+        assert.equal(hasUnsentMentions(d, A), false, "the uncapped remainder must not re-wake");
+        assert.equal(pendingMentions(d, A, 10).total, 25, "but it is still owed to the agent");
+    });
+    it("shows the most recent when capped, oldest-first within the slice", () => {
+        const d = db();
+        for (let seq = 1; seq <= 5; seq++)
+            mention(d, seq);
+        const { rows } = pendingMentions(d, A, 3);
+        assert.deepEqual(rows.map((r) => r.seq), [3, 4, 5]);
+    });
+});
+describe("receiving the event is the acknowledgment", () => {
+    it("settles exactly the events delivered, not a range", () => {
+        const d = db();
+        for (const seq of [5, 7, 9])
+            mention(d, seq);
+        assert.equal(pendingMentions(d, A, 10).total, 3);
+        // The read returned seq 7 and 9 — a `before` bound, or a `tail`, can skip
+        // what lies between. Settling on "seq > 5" would mark all three read.
+        assert.equal(ackMentionsByRead(d, A, { [B]: [7, 9] }), 2);
+        const rest = pendingMentions(d, A, 10);
+        assert.equal(rest.total, 1);
+        assert.equal(rest.rows[0].seq, 5, "the event that was never shown is still owed");
+    });
+    it("settles nothing when the delivered events carry no mention", () => {
+        const d = db();
+        mention(d, 5);
+        assert.equal(ackMentionsByRead(d, A, { [B]: [4, 6, 99] }), 0);
+        assert.equal(pendingMentions(d, A, 10).total, 1);
+    });
+    it("ignores a read of an unrelated narrative", () => {
+        const d = db();
+        mention(d, 5);
+        assert.equal(ackMentionsByRead(d, A, { [C]: [5] }), 0);
+        assert.equal(pendingMentions(d, A, 10).total, 1);
+    });
+    it("ignores an empty delivery", () => {
+        const d = db();
+        mention(d, 5);
+        assert.equal(ackMentionsByRead(d, A, { [B]: [] }), 0);
+        assert.equal(ackMentionsByRead(d, A, {}), 0);
+        assert.equal(pendingMentions(d, A, 10).total, 1);
+    });
+    it("reading your own log is not evidence you looked at someone else's", () => {
+        const d = db();
+        mention(d, 5, A, A); // pathological, but the guard must hold
+        assert.equal(ackMentionsByRead(d, A, { [A]: [5] }), 0);
+    });
+    it("settles one source without touching another, in either recording order", () => {
+        // The bug that forced per-row marks. A single high-water over a shared id
+        // space settles every mention with a lower id when one is acknowledged —
+        // including one from a narrative the agent never looked at. Recording C
+        // *first* is what exposes it, so both orders are pinned.
+        for (const [first] of [[B], [C]]) {
+            const d = db();
+            mention(d, 5, first);
+            mention(d, 5, first === B ? C : B);
+            assert.equal(pendingMentions(d, A, 10).total, 2);
+            ackMentionsByRead(d, A, { [B]: [5] });
+            const rest = pendingMentions(d, A, 10);
+            assert.equal(rest.total, 1, `reading B settled C's mention (${first} recorded first)`);
+            assert.equal(rest.rows[0].src, C);
+        }
+    });
+    it("is idempotent", () => {
+        const d = db();
+        mention(d, 5);
+        assert.equal(ackMentionsByRead(d, A, { [B]: [5] }), 1);
+        assert.equal(ackMentionsByRead(d, A, { [B]: [5] }), 0);
+        assert.equal(pendingMentions(d, A, 10).total, 0);
+    });
+});
+describe("annotating delivered events", () => {
+    it("says what each event addresses, keyed by nid:seq", () => {
+        const d = db();
+        recordMentions(d, { mentionedNids: [A, C], srcNarrative: B, srcSeq: 5, author: B, time: 1 });
+        const ann = mentionsInEvents(d, { [B]: [4, 5, 6] });
+        assert.deepEqual(Object.keys(ann), [`${B}:5`]);
+        assert.deepEqual(ann[`${B}:5`].sort(), [A, C].sort());
+    });
+    it("is empty for events that mention nobody, so the common case costs nothing", () => {
+        const d = db();
+        mention(d, 5);
+        assert.deepEqual(mentionsInEvents(d, { [B]: [1, 2, 3] }), {});
+        assert.deepEqual(mentionsInEvents(d, {}), {});
+    });
+    it("reports regardless of either mark", () => {
+        const d = db();
+        mention(d, 5);
+        markSent(d, A);
+        ackMentionsByRead(d, A, { [B]: [5] });
+        // The event still mentions A; it just isn't owed any more.
+        assert.deepEqual(mentionsInEvents(d, { [B]: [5] }), { [`${B}:5`]: [A] });
+    });
+});
+describe("recovery and dismissal", () => {
+    it("allMentions ignores both marks and moves neither", () => {
+        const d = db();
+        mention(d, 5);
+        markSent(d, A);
+        ackMentionsByRead(d, A, { [B]: [1, 2, 3, 5] });
+        assert.equal(pendingMentions(d, A, 10).total, 0);
+        // Delivery is at-most-once — a tool result can be dropped by a socket that
+        // closes mid-flight — so "settled" must never mean "unreachable".
+        assert.equal(allMentions(d, A, 10).length, 1);
+        assert.equal(pendingMentions(d, A, 10).total, 0, "reading recovery settles nothing");
+        assert.equal(hasUnsentMentions(d, A), false, "and wakes nobody");
+    });
+    it("dismiss settles everything currently recorded, and nothing later", () => {
+        const d = db();
+        mention(d, 5);
+        mention(d, 6);
+        assert.equal(dismissMentions(d, A), 2);
+        assert.equal(pendingMentions(d, A, 10).total, 0);
+        mention(d, 7);
+        assert.equal(pendingMentions(d, A, 10).total, 1, "a later mention is unaffected");
+        assert.ok(hasUnsentMentions(d, A), "and still wakes");
+    });
+    it("dismiss on an empty ledger is a no-op", () => {
+        const d = db();
+        assert.equal(dismissMentions(d, A), 0);
+    });
+});
+describe("cross-brane", () => {
+    it("stamps brane_id only when it differs from the reader's", () => {
+        const d = db();
+        mention(d, 1, C); // C lives in brane-far
+        mention(d, 1, B); // B is home
+        const rows = pendingMentions(d, A, 10, "brane-home").rows;
+        const fromFar = rows.find((r) => r.src === C);
+        const fromHome = rows.find((r) => r.src === B);
+        assert.equal(fromFar?.brane_id, "brane-far");
+        assert.equal(fromHome?.brane_id, undefined);
+    });
+    it("carries the author separately from the source narrative", () => {
+        const d = db();
+        // C narrated into B's narrative, mentioning A: read B, but C said it.
+        recordMentions(d, {
+            mentionedNids: [A],
+            srcNarrative: B,
+            srcSeq: 3,
+            author: C,
+            time: 1,
+        });
+        const row = pendingMentions(d, A, 10).rows[0];
+        assert.equal(row.src, B, "where to read");
+        assert.equal(row.author, C, "who said it");
+    });
+});
+//# sourceMappingURL=mentions-ledger.test.js.map