brane 0.1.1 → 0.3.1

package/dist/test/mcp-bridge-reconnect.test.js

@@ -0,0 +1,121 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { WebSocketServer } from "ws";
+// The bridge across a lost connection, driven for real: a child process runs
+// `startMcpBridge` against a WebSocket server this test plays daemon on, and the
+// test plays the agent on the child's stdio.
+//
+// A call the bridge had *sent* when the connection went is ambiguous — the
+// daemon may have run it — so the agent is told so. A call still *queued* was
+// never sent, and must go out on reconnect exactly once, with no error. The
+// bridge used to fail both, and then send the queued one anyway: an error the
+// agent would act on (retrying ran the call twice), and a waiting narrate
+// parked on the daemon with nobody left to answer it.
+const BRIDGE = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), "..", "mcp", "server.js")).href;
+function childEnv(port) {
+    const env = { ...process.env, PORT: String(port), HOME: mkdtempSync(join(tmpdir(), "brane-bridge-")) };
+    // Whatever session this suite runs inside must not leak into the child's dial.
+    for (const k of Object.keys(env)) {
+        if (k.startsWith("BRANE_") || k === "CLAUDE_CODE_SESSION_ID" || k === "NODE_TEST_CONTEXT")
+            delete env[k];
+    }
+    return env;
+}
+describe("the MCP bridge across a lost connection", () => {
+    it("fails the call it had sent, and sends the queued one once, without an error", async () => {
+        const received = [];
+        const urls = [];
+        let conn = 0;
+        const sockets = [];
+        const server = createServer();
+        const wss = new WebSocketServer({ noServer: true });
+        server.on("upgrade", (req, sock, head) => {
+            const n = ++conn;
+            urls.push(req.url ?? "");
+            // The second dial is refused, so the queued call has to survive a failed
+            // reconnect (which fires `close`, and with it the fail path) too.
+            if (n === 2) {
+                sock.write("HTTP/1.1 503 Busy\r\n\r\n");
+                sock.destroy();
+                return;
+            }
+            wss.handleUpgrade(req, sock, head, (ws) => {
+                sockets.push(ws);
+                ws.send(JSON.stringify({ type: "welcome", brane_id: "b", narrative_id: "external-test0001", bind_secret: "s3cret" }));
+                ws.on("message", (d) => {
+                    const msg = JSON.parse(d.toString());
+                    received.push({ conn: n, msg });
+                    if (n === 1 && msg.type === "tool_call") {
+                        ws.terminate(); // the daemon took the call and the connection died
+                    }
+                    else if (msg.type === "tool_call") {
+                        ws.send(JSON.stringify({ type: "tool_result", id: msg.id, result: { ok: msg.tool } }));
+                    }
+                });
+            });
+        });
+        await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
+        const port = server.address().port;
+        const child = spawn(process.execPath, ["--input-type=module", "-e",
+            `const { startMcpBridge } = await import(${JSON.stringify(BRIDGE)});
+         startMcpBridge(async () => "ws://127.0.0.1:" + process.env.PORT + "/ws/mcp?token=t");`], { env: childEnv(port), stdio: ["pipe", "pipe", "pipe"] });
+        const replies = new Map();
+        let buf = "";
+        child.stdout.on("data", (d) => {
+            buf += d.toString();
+            let i;
+            while ((i = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (line.trim()) {
+                    const m = JSON.parse(line);
+                    replies.set(m.id, m);
+                }
+            }
+        });
+        const call = (id, name, args) => child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }) + "\n");
+        const until = async (pred, ms) => {
+            const end = Date.now() + ms;
+            while (!pred()) {
+                if (Date.now() > end)
+                    throw new Error("timed out waiting");
+                await new Promise((r) => setTimeout(r, 25));
+            }
+        };
+        try {
+            await until(() => sockets.length === 1, 3000);
+            call(1, "narrate", { say: "hello", wait: true }); // sent on conn 1, then the conn dies
+            await until(() => replies.has(1), 3000);
+            call(2, "listen", { after: 1, wait: false }); // queued: no connection right now
+            await until(() => replies.has(2), 8000); // answered by conn 3
+            const r1 = replies.get(1).result;
+            assert.equal(r1.isError, true, "the sent call is ambiguous and says so");
+            assert.match(r1.content[0].text, /may already have been posted/);
+            const r2 = replies.get(2).result;
+            assert.ok(!r2.isError, "the queued call was never sent, so it is not failed");
+            assert.deepEqual(JSON.parse(r2.content[0].text), { ok: "listen" });
+            const calls = received.filter((f) => f.msg.type === "tool_call");
+            assert.deepEqual(calls.map((f) => [f.conn, f.msg.tool]), [[1, "narrate"], [3, "listen"]], "each call reaches the daemon exactly once: the failed one is not replayed");
+            // #497: an unspawned client adopts the narrative *and* the secret its
+            // first welcome hands it, so its reconnect proves it rather than being
+            // refused and minted a different narrative.
+            const redial = new URL(urls[2], "ws://x");
+            assert.equal(redial.searchParams.get("nid"), "external-test0001");
+            assert.equal(redial.searchParams.get("secret"), "s3cret");
+        }
+        finally {
+            child.kill();
+            for (const s of sockets)
+                s.terminate();
+            wss.close();
+            server.close();
+        }
+    });
+});
+//# sourceMappingURL=mcp-bridge-reconnect.test.js.map

package/dist/test/mcp-narrative.test.js

@@ -0,0 +1,193 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { adoptBindTokens } from "../db/tokens.js";
+import { ensureMcpNarrative, mintExternalNarrative, mintExternalNarrativeWithSecret, resolveMcpBind, randomBase36 } from "../daemon/server.js";
+function getNarrative(db, id) {
+    return db
+        .prepare("SELECT id, brane_id, agent_type, role, status FROM narratives WHERE id = ?")
+        .get(id);
+}
+function narrativeCount(db) {
+    return db.prepare("SELECT COUNT(*) as n FROM narratives").get().n;
+}
+describe("randomBase36", () => {
+    it("produces a string of the requested length", () => {
+        for (const len of [1, 8, 16, 64]) {
+            assert.equal(randomBase36(len).length, len);
+        }
+    });
+    it("uses only [0-9a-z]", () => {
+        // Draw a large sample so every output character is exercised many times.
+        const s = randomBase36(2000);
+        assert.match(s, /^[0-9a-z]+$/);
+    });
+    it("covers the full alphabet without bias-induced gaps", () => {
+        // Rejection sampling must still reach every symbol, including the high
+        // ones (z = index 35) that a naive `byte % 36` would over- or
+        // under-represent. With 5000 draws, all 36 symbols should appear.
+        const seen = new Set(randomBase36(5000).split(""));
+        assert.equal(seen.size, 36, `expected all 36 symbols, saw ${seen.size}`);
+    });
+});
+describe("ensureMcpNarrative", () => {
+    it("trusts an id that already names a narrative row (no INSERT, no event)", () => {
+        const db = createTestDb();
+        db.prepare(`INSERT INTO narratives (id, brane_id, agent_type, role, created_at, status)
+       VALUES ('claude-deadbeef', 'brane-test', 'claude', 'reviewer', 0, 'ended')`).run();
+        const before = narrativeCount(db);
+        const result = ensureMcpNarrative(db, "brane-test", "claude-deadbeef");
+        assert.equal(result, "claude-deadbeef");
+        assert.equal(narrativeCount(db), before, "must not insert a new row");
+        // No seeded event for an existing narrative.
+        const events = db
+            .prepare("SELECT COUNT(*) as n FROM events WHERE narrative_id = ?")
+            .get("claude-deadbeef");
+        assert.equal(events.n, 0);
+    });
+    it("mints a fresh server-side narrative for an unknown (unspawned) id", () => {
+        const db = createTestDb();
+        const result = ensureMcpNarrative(db, "brane-test", "external-clientchosen");
+        // The client-chosen id is discarded; a server id of the canonical shape
+        // is returned instead.
+        assert.notEqual(result, "external-clientchosen");
+        assert.match(result, /^external-[0-9a-z]{8}$/);
+        assert.equal(getNarrative(db, "external-clientchosen"), undefined, "client id must not be persisted");
+        const row = getNarrative(db, result);
+        assert.ok(row, "minted narrative row should exist");
+        assert.equal(row.brane_id, "brane-test");
+        assert.equal(row.agent_type, "external");
+        assert.equal(row.role, "external");
+        assert.equal(row.status, "active");
+    });
+    it("seeds a single `started` event on the minted narrative", () => {
+        const db = createTestDb();
+        const result = ensureMcpNarrative(db, "brane-test", "external-clientchosen");
+        const events = db
+            .prepare("SELECT seq, type, content FROM events WHERE narrative_id = ? ORDER BY seq")
+            .all(result);
+        assert.equal(events.length, 1);
+        assert.equal(events[0].seq, 1);
+        assert.equal(events[0].type, "started");
+        assert.equal(events[0].content, "Connected external MCP client");
+    });
+    it("mints distinct, unique narratives across repeated unspawned connects", () => {
+        // Exercises the uniqueness contract: every unspawned connect produces a
+        // fresh row whose id collides with neither the client-supplied value nor
+        // any previously minted id. (The internal PRIMARY KEY retry loop is a
+        // vanishingly-rare defensive branch and isn't forced here.)
+        const db = createTestDb();
+        const ids = new Set();
+        for (let i = 0; i < 50; i++) {
+            ids.add(ensureMcpNarrative(db, "brane-test", "external-placeholder"));
+        }
+        assert.equal(ids.size, 50, "every unspawned connect should mint a unique id");
+        assert.equal(narrativeCount(db), 50);
+    });
+});
+describe("resolveMcpBind (per-narrative bind token)", () => {
+    // Seed a spawned narrative with a known bind_token + session, and return
+    // helpers to inspect it after a bind attempt.
+    function seedSpawned(db, id, bindToken, sessionId = "sess-A") {
+        db.prepare(`INSERT INTO narratives (id, brane_id, agent_type, role, created_at, status, agent_session_id, bind_token)
+       VALUES (?, 'brane-test', 'claude', 'worker', 0, 'active', ?, ?)`).run(id, sessionId, bindToken);
+        // As the daemon's start does: the plaintext becomes an agent token row.
+        adoptBindTokens(db);
+    }
+    function eventCount(db, id) {
+        return db.prepare("SELECT COUNT(*) as n FROM events WHERE narrative_id = ?").get(id).n;
+    }
+    function sessionOf(db, id) {
+        return db.prepare("SELECT agent_session_id FROM narratives WHERE id = ?").get(id).agent_session_id;
+    }
+    it("binds to the claimed id when the secret matches", () => {
+        const db = createTestDb();
+        seedSpawned(db, "claude-alpha", "secret-alpha");
+        const result = resolveMcpBind(db, "brane-test", "claude-alpha", "secret-alpha");
+        assert.equal(result.nid, "claude-alpha");
+        assert.equal(result.minted, false);
+        assert.equal(result.rejected, undefined);
+    });
+    it("rejects a wrong secret: mints external, leaves the claimed narrative untouched", () => {
+        const db = createTestDb();
+        seedSpawned(db, "claude-alpha", "secret-alpha", "sess-A");
+        const result = resolveMcpBind(db, "brane-test", "claude-alpha", "wrong-secret");
+        assert.notEqual(result.nid, "claude-alpha");
+        assert.match(result.nid, /^external-[0-9a-z]{8}$/);
+        assert.equal(result.minted, true);
+        assert.deepEqual(result.rejected, { claimedNid: "claude-alpha", reason: "secret_mismatch" });
+        // The claimed narrative's session is preserved and nothing leaked into it.
+        assert.equal(sessionOf(db, "claude-alpha"), "sess-A", "victim session must be preserved");
+        assert.equal(eventCount(db, "claude-alpha"), 0, "no events leak into the claimed narrative");
+    });
+    it("rejects an absent secret (reason: secret_absent)", () => {
+        const db = createTestDb();
+        seedSpawned(db, "claude-alpha", "secret-alpha");
+        const result = resolveMcpBind(db, "brane-test", "claude-alpha", undefined);
+        assert.match(result.nid, /^external-[0-9a-z]{8}$/);
+        assert.equal(result.minted, true);
+        assert.deepEqual(result.rejected, { claimedNid: "claude-alpha", reason: "secret_absent" });
+        assert.equal(sessionOf(db, "claude-alpha"), "sess-A");
+    });
+    it("mints a fresh external narrative for an unknown (unspawned) id", () => {
+        const db = createTestDb();
+        const result = resolveMcpBind(db, "brane-test", "external-clientchosen", undefined);
+        assert.notEqual(result.nid, "external-clientchosen");
+        assert.match(result.nid, /^external-[0-9a-z]{8}$/);
+        assert.equal(result.minted, true);
+        assert.equal(result.rejected, undefined);
+        assert.equal(getNarrative(db, "external-clientchosen"), undefined, "client-chosen id must not be persisted");
+    });
+    it("a row with a null bind_token is refused, not waved through", () => {
+        // The migration grace that used to allow this bind is retired. Such a row
+        // has no secret to check against, so there is no way to prove a claim to
+        // it: the connection is minted a fresh external id like any other unproven
+        // claimant, and the reason names the row rather than the client.
+        const db = createTestDb();
+        seedSpawned(db, "claude-legacy", null);
+        const result = resolveMcpBind(db, "brane-test", "claude-legacy", undefined);
+        assert.match(result.nid, /^external-[0-9a-z]{8}$/);
+        assert.equal(result.minted, true);
+        assert.deepEqual(result.rejected, { claimedNid: "claude-legacy", reason: "no_bind_token" });
+        assert.equal(sessionOf(db, "claude-legacy"), "sess-A", "claimed narrative untouched");
+        assert.equal(eventCount(db, "claude-legacy"), 0);
+    });
+    it("a matching secret string that differs from the token is still rejected", () => {
+        // Guards against any accidental loose/prefix comparison.
+        const db = createTestDb();
+        seedSpawned(db, "claude-alpha", "secret-alpha");
+        const result = resolveMcpBind(db, "brane-test", "claude-alpha", "secret-alph");
+        assert.equal(result.minted, true);
+        assert.deepEqual(result.rejected, { claimedNid: "claude-alpha", reason: "secret_mismatch" });
+    });
+});
+describe("mintExternalNarrative", () => {
+    it("creates an external-shaped row with a seeded started event", () => {
+        const db = createTestDb();
+        const nid = mintExternalNarrative(db, "brane-test");
+        assert.match(nid, /^external-[0-9a-z]{8}$/);
+        const row = getNarrative(db, nid);
+        assert.ok(row);
+        assert.equal(row.agent_type, "external");
+        assert.equal(row.role, "external");
+        assert.equal(row.status, "active");
+        const events = db
+            .prepare("SELECT type, content FROM events WHERE narrative_id = ?")
+            .all(nid);
+        assert.equal(events.length, 1);
+        assert.equal(events[0].type, "started");
+    });
+    it("gives the external a bind token, so its own reconnect authenticates", () => {
+        // Externals used to be tokenless, and their reconnects relied on the
+        // migration grace to get back to the same narrative. With the grace gone
+        // that would fragment one client into a narrative per reconnect, so the
+        // mint issues a real secret and `welcome` hands it to the bridge.
+        const db = createTestDb();
+        const { nid, secret } = mintExternalNarrativeWithSecret(db, "brane-test");
+        assert.ok(secret, "minted externals carry an agent token");
+        const { bind_token } = db.prepare("SELECT bind_token FROM narratives WHERE id = ?").get(nid);
+        assert.equal(bind_token, null, "and no plaintext of it is kept");
+        assert.equal(resolveMcpBind(db, "brane-test", nid, secret).nid, nid);
+    });
+});
+//# sourceMappingURL=mcp-narrative.test.js.map