chapterhouse 0.1.1

package/dist/api/server.test.js

@@ -0,0 +1,385 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdirSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import test from "node:test";
+test("supports API_TOKEN env var and personal health route helpers", async () => {
+    const runtime = await import("./server-runtime.js");
+    assert.equal(typeof runtime.resolveApiToken, "function", "resolveApiToken should be exported");
+    assert.equal(typeof runtime.shouldServeSpaPath, "function", "shouldServeSpaPath should be exported");
+    assert.equal(typeof runtime.createHealthPayload, "function", "createHealthPayload should be exported");
+    assert.equal(typeof runtime.createPublicConfigPayload, "function", "createPublicConfigPayload should be exported");
+    assert.equal(typeof runtime.getDisplayHost, "function", "getDisplayHost should be exported");
+    assert.equal(typeof runtime.assertAuthenticationConfigured, "function", "assertAuthenticationConfigured should be exported");
+    const token = runtime.resolveApiToken({
+        envToken: "personal-token",
+        tokenPath: "/tmp/chapterhouse-api-token",
+    });
+    assert.equal(token, "personal-token");
+    assert.equal(runtime.shouldServeSpaPath("/health"), false);
+    assert.equal(runtime.getDisplayHost("0.0.0.0"), "localhost");
+    assert.deepEqual(runtime.createHealthPayload(new Date("2026-05-06T00:00:00.000Z")), {
+        status: "ok",
+        timestamp: "2026-05-06T00:00:00.000Z",
+    });
+    assert.deepEqual(runtime.createPublicConfigPayload({
+        entraAuthEnabled: true,
+        standaloneMode: false,
+        entraClientId: "client-id",
+        entraTenantId: "tenant-id",
+    }), {
+        appName: "Chapterhouse",
+        entraAuthEnabled: true,
+        entraClientId: "client-id",
+        entraTenantId: "tenant-id",
+    });
+    assert.deepEqual(runtime.createPublicConfigPayload({
+        entraAuthEnabled: false,
+        standaloneMode: false,
+        entraClientId: "client-id",
+        entraTenantId: "tenant-id",
+    }), {
+        appName: "Chapterhouse",
+        entraAuthEnabled: false,
+        standalone: false,
+    });
+    assert.doesNotThrow(() => runtime.assertAuthenticationConfigured({
+        entraAuthEnabled: false,
+        apiToken: null,
+    }));
+    assert.doesNotThrow(() => runtime.assertAuthenticationConfigured({
+        entraAuthEnabled: false,
+        apiToken: "personal-token",
+    }));
+    assert.doesNotThrow(() => runtime.assertAuthenticationConfigured({
+        entraAuthEnabled: true,
+        apiToken: null,
+    }));
+});
+test("formats named SSE status events", async () => {
+    const sse = await import("./sse.js");
+    assert.equal(typeof sse.formatSseEvent, "function", "formatSseEvent should be exported");
+    assert.equal(sse.formatSseEvent("status", { status: "dreaming", message: "Consolidating memories..." }), 'event: status\ndata: {"status":"dreaming","message":"Consolidating memories..."}\n\n');
+});
+test("buildHistoryEntries resolves wiki files through the shared path resolver", async () => {
+    const runtime = await import("./server-runtime.js");
+    assert.equal(typeof runtime.buildHistoryEntries, "function", "buildHistoryEntries should be exported");
+    const seen = [];
+    const entries = runtime.buildHistoryEntries([
+        "pages/conversations/older.md",
+        "pages/conversations/newer.md",
+    ], {
+        resolveWikiPath: (pageId) => {
+            seen.push(pageId);
+            return `/wiki/${pageId}`;
+        },
+        stat: (fullPath) => ({
+            mtimeMs: fullPath.endsWith("newer.md") ? 200 : 100,
+        }),
+    });
+    assert.deepEqual(seen, [
+        "pages/conversations/older.md",
+        "pages/conversations/newer.md",
+    ]);
+    assert.deepEqual(entries, [
+        { path: "pages/conversations/newer.md", mtime: 200 },
+        { path: "pages/conversations/older.md", mtime: 100 },
+    ]);
+});
+const repoRoot = process.cwd();
+const serverTestRoot = join(repoRoot, ".test-work", `server-routes-${process.pid}`);
+async function getFreePort() {
+    const server = createServer();
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    assert.ok(address && typeof address === "object", "server should expose a bound address");
+    await new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    });
+    return address.port;
+}
+async function stopChild(child) {
+    if (child.exitCode !== null) {
+        return;
+    }
+    child.kill("SIGTERM");
+    await new Promise((resolve) => {
+        child.once("exit", () => resolve());
+        setTimeout(() => {
+            if (child.exitCode === null) {
+                child.kill("SIGKILL");
+            }
+        }, 2_000);
+    });
+}
+// Standalone mode triggers a full daemon init via the server→daemon circular import
+// (server.ts imports restartDaemon from daemon.ts, which has module-level main()).
+// The Copilot SDK's client.start() then blocks the event loop while authenticating,
+// so the HTTP server cannot respond until SDK init completes (~10-20 s depending on
+// session state).  Other modes complete in ~330 ms because the SDK yields quickly.
+// Root cause tracked in .squad/decisions/ for Kaylee (backend fix: lazy-import or
+// guard env var in daemon.ts).  Interim fix: 30 s timeout for standalone, 10 s elsewhere.
+// Additionally, strip COPILOT_* env vars from the child so it doesn't accidentally
+// piggy-back on the running agent session, which worsens the blocking behaviour.
+async function withStartedServer(run, extraEnv = {}, timeoutMs = 10_000) {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(serverTestRoot, { recursive: true, force: true });
+    mkdirSync(serverTestRoot, { recursive: true });
+    const port = await getFreePort();
+    const logs = [];
+    const child = spawn(process.execPath, [
+        "--input-type=module",
+        "-e",
+        "import { startApiServer } from './dist/api/server.js'; await startApiServer();",
+    ], {
+        cwd: repoRoot,
+        env: {
+            // Strip COPILOT_* vars so the child process doesn't inherit the running
+            // agent's session credentials, which causes the SDK to hang in standalone mode.
+            ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("COPILOT_"))),
+            CHAPTERHOUSE_DISABLE_DOTENV: "1",
+            CHAPTERHOUSE_HOME: serverTestRoot,
+            API_HOST: "127.0.0.1",
+            API_PORT: String(port),
+            API_TOKEN: "route-token",
+            ...extraEnv,
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.on("data", (chunk) => logs.push(String(chunk)));
+    child.stderr?.on("data", (chunk) => logs.push(String(chunk)));
+    const baseUrl = `http://127.0.0.1:${port}`;
+    try {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (child.exitCode !== null) {
+                throw new Error(`API server exited early:\n${logs.join("")}`);
+            }
+            try {
+                const response = await fetch(`${baseUrl}/status`);
+                if (response.ok) {
+                    await run({ baseUrl, authHeader: "Bearer route-token" });
+                    return;
+                }
+            }
+            catch {
+                // Server still starting.
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error(`Timed out waiting for API server to start:\n${logs.join("")}`);
+    }
+    finally {
+        await stopChild(child);
+        rmSync(serverTestRoot, { recursive: true, force: true });
+    }
+}
+test("server routes expose bootstrap and public config without auth", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const bootstrap = await fetch(`${baseUrl}/api/bootstrap`);
+        assert.equal(bootstrap.status, 200);
+        assert.deepEqual(await bootstrap.json(), { authMode: "legacy", token: "route-token" });
+        const publicConfig = await fetch(`${baseUrl}/api/config/public`);
+        assert.equal(publicConfig.status, 200);
+        assert.deepEqual(await publicConfig.json(), {
+            appName: "Chapterhouse",
+            entraAuthEnabled: false,
+            standalone: false,
+        });
+    });
+});
+test("server runs in standalone mode without auth", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const bootstrap = await fetch(`${baseUrl}/api/bootstrap`);
+        assert.equal(bootstrap.status, 200);
+        assert.deepEqual(await bootstrap.json(), { authMode: "standalone" });
+        const publicConfig = await fetch(`${baseUrl}/api/config/public`);
+        assert.equal(publicConfig.status, 200);
+        assert.deepEqual(await publicConfig.json(), {
+            appName: "Chapterhouse",
+            entraAuthEnabled: false,
+            standalone: true,
+        });
+        const model = await fetch(`${baseUrl}/api/model`);
+        assert.equal(model.status, 200);
+        assert.deepEqual(await model.json(), { model: "claude-sonnet-4.6" });
+    }, {
+        API_TOKEN: "",
+    }, 30_000);
+});
+test("server bootstrap rejects non-loopback origins", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const response = await fetch(`${baseUrl}/api/bootstrap`, {
+            headers: { origin: "https://evil.example" },
+        });
+        assert.equal(response.status, 403);
+        assert.deepEqual(await response.json(), { error: "Bootstrap is loopback-only" });
+    });
+});
+test("server applies security headers and allows loopback CORS during development", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const response = await fetch(`${baseUrl}/api/config/public`, {
+            headers: { origin: "http://localhost:5173" },
+        });
+        assert.equal(response.status, 200);
+        assert.equal(response.headers.get("access-control-allow-origin"), "http://localhost:5173");
+        assert.equal(response.headers.get("x-content-type-options"), "nosniff");
+        assert.equal(response.headers.get("x-dns-prefetch-control"), "off");
+    });
+});
+test("server only enables production CORS for explicit origins", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const allowed = await fetch(`${baseUrl}/api/config/public`, {
+            headers: { origin: "https://app.example.com" },
+        });
+        assert.equal(allowed.status, 200);
+        assert.equal(allowed.headers.get("access-control-allow-origin"), "https://app.example.com");
+        const blocked = await fetch(`${baseUrl}/api/config/public`, {
+            headers: { origin: "https://evil.example" },
+        });
+        assert.equal(blocked.status, 200);
+        assert.equal(blocked.headers.get("access-control-allow-origin"), null);
+    }, {
+        NODE_ENV: "production",
+        CORS_ALLOWED_ORIGINS: "https://app.example.com",
+    });
+});
+test("server wiki routes support authenticated CRUD", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const createResponse = await fetch(`${baseUrl}/api/wiki/page?path=pages/shared/runbooks/deploy.md`, {
+            method: "PUT",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ content: "# Deploy\n" }),
+        });
+        assert.equal(createResponse.status, 200);
+        assert.deepEqual(await createResponse.json(), {
+            ok: true,
+            created: true,
+            path: "pages/shared/runbooks/deploy.md",
+        });
+        const getResponse = await fetch(`${baseUrl}/api/wiki/page?path=pages/shared/runbooks/deploy.md`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(getResponse.status, 200);
+        assert.deepEqual(await getResponse.json(), {
+            path: "pages/shared/runbooks/deploy.md",
+            content: "# Deploy\n",
+        });
+        const deleteResponse = await fetch(`${baseUrl}/api/wiki/page?path=pages/shared/runbooks/deploy.md`, {
+            method: "DELETE",
+            headers: { authorization: authHeader },
+        });
+        assert.equal(deleteResponse.status, 200);
+        assert.deepEqual(await deleteResponse.json(), {
+            ok: true,
+            path: "pages/shared/runbooks/deploy.md",
+        });
+        const missingResponse = await fetch(`${baseUrl}/api/wiki/page?path=pages/shared/runbooks/deploy.md`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(missingResponse.status, 404);
+        assert.deepEqual(await missingResponse.json(), { error: "Page not found" });
+    });
+});
+test("server message route validates the SSE connection id", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const response = await fetch(`${baseUrl}/api/message`, {
+            method: "POST",
+            headers: {
+                authorization: authHeader,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                prompt: "Hello there",
+                connectionId: "missing-connection",
+            }),
+        });
+        assert.equal(response.status, 400);
+        assert.deepEqual(await response.json(), {
+            error: "Missing or invalid 'connectionId'. Connect to /stream first.",
+        });
+    });
+});
+test("server rate limits authenticated API routes", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const first = await fetch(`${baseUrl}/api/model`, {
+            headers: { authorization: authHeader },
+        });
+        const second = await fetch(`${baseUrl}/api/model`, {
+            headers: { authorization: authHeader },
+        });
+        const third = await fetch(`${baseUrl}/api/model`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(first.status, 200);
+        assert.equal(second.status, 200);
+        assert.equal(third.status, 429);
+        assert.equal(third.headers.get("retry-after"), "60");
+        assert.deepEqual(await third.json(), {
+            error: "Too many API requests. Retry after 60 seconds.",
+        });
+    }, {
+        API_RATE_LIMIT_GENERAL_MAX: "2",
+    });
+});
+test("server rate limits bootstrap auth requests", async () => {
+    await withStartedServer(async ({ baseUrl }) => {
+        const first = await fetch(`${baseUrl}/api/bootstrap`);
+        const second = await fetch(`${baseUrl}/api/bootstrap`);
+        const third = await fetch(`${baseUrl}/api/bootstrap`);
+        assert.equal(first.status, 200);
+        assert.equal(second.status, 200);
+        assert.equal(third.status, 429);
+        assert.equal(third.headers.get("retry-after"), "60");
+        assert.deepEqual(await third.json(), {
+            error: "Too many authentication attempts. Retry after 60 seconds.",
+        });
+    }, {
+        API_RATE_LIMIT_AUTH_MAX: "2",
+    });
+});
+test("server caps concurrent SSE connections per IP", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const firstController = new AbortController();
+        const secondController = new AbortController();
+        let firstResponse;
+        let secondResponse;
+        try {
+            firstResponse = await fetch(`${baseUrl}/stream`, {
+                headers: { authorization: authHeader },
+                signal: firstController.signal,
+            });
+            secondResponse = await fetch(`${baseUrl}/stream`, {
+                headers: { authorization: authHeader },
+                signal: secondController.signal,
+            });
+            assert.equal(firstResponse.status, 200);
+            assert.equal(secondResponse.status, 200);
+            const rejected = await fetch(`${baseUrl}/stream`, {
+                headers: { authorization: authHeader },
+            });
+            assert.equal(rejected.status, 429);
+            assert.equal(rejected.headers.get("retry-after"), "60");
+            assert.deepEqual(await rejected.json(), {
+                error: "Too many concurrent stream connections. Retry after 60 seconds.",
+            });
+        }
+        finally {
+            firstController.abort();
+            secondController.abort();
+            await Promise.allSettled([
+                firstResponse?.body?.cancel() ?? Promise.resolve(),
+                secondResponse?.body?.cancel() ?? Promise.resolve(),
+            ]);
+        }
+    }, {
+        API_RATE_LIMIT_SSE_MAX_CONNECTIONS: "2",
+    });
+});
+//# sourceMappingURL=server.test.js.map

package/dist/api/sse.integration.test.js

@@ -0,0 +1,270 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdirSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import test from "node:test";
+// ---------------------------------------------------------------------------
+// Server harness (copied from server.test.ts; distinct root path suffix to
+// avoid collision when both test files run in parallel in the same process).
+// ---------------------------------------------------------------------------
+const repoRoot = process.cwd();
+const sseTestRoot = join(repoRoot, ".test-work", `sse-integration-${process.pid}`);
+async function getFreePort() {
+    const server = createServer();
+    await new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    assert.ok(address && typeof address === "object", "server should expose a bound address");
+    await new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    });
+    return address.port;
+}
+async function stopChild(child) {
+    if (child.exitCode !== null) {
+        return;
+    }
+    child.kill("SIGTERM");
+    await new Promise((resolve) => {
+        child.once("exit", () => resolve());
+        setTimeout(() => {
+            if (child.exitCode === null) {
+                child.kill("SIGKILL");
+            }
+        }, 2_000);
+    });
+}
+async function withStartedServer(run, extraEnv = {}, timeoutMs = 10_000) {
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    rmSync(sseTestRoot, { recursive: true, force: true });
+    mkdirSync(sseTestRoot, { recursive: true });
+    const port = await getFreePort();
+    const logs = [];
+    const child = spawn(process.execPath, [
+        "--input-type=module",
+        "-e",
+        "import { startApiServer } from './dist/api/server.js'; await startApiServer();",
+    ], {
+        cwd: repoRoot,
+        env: {
+            // Strip COPILOT_* vars so the child does not inherit the running
+            // agent session credentials, which causes the SDK to hang in standalone mode.
+            ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("COPILOT_"))),
+            CHAPTERHOUSE_DISABLE_DOTENV: "1",
+            CHAPTERHOUSE_HOME: sseTestRoot,
+            API_HOST: "127.0.0.1",
+            API_PORT: String(port),
+            API_TOKEN: "route-token",
+            ...extraEnv,
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.on("data", (chunk) => logs.push(String(chunk)));
+    child.stderr?.on("data", (chunk) => logs.push(String(chunk)));
+    const baseUrl = `http://127.0.0.1:${port}`;
+    try {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (child.exitCode !== null) {
+                throw new Error(`API server exited early:\n${logs.join("")}`);
+            }
+            try {
+                const response = await fetch(`${baseUrl}/status`);
+                if (response.ok) {
+                    await run({ baseUrl, authHeader: "Bearer route-token" });
+                    return;
+                }
+            }
+            catch {
+                // Server still starting.
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error(`Timed out waiting for API server to start:\n${logs.join("")}`);
+    }
+    finally {
+        await stopChild(child);
+        rmSync(sseTestRoot, { recursive: true, force: true });
+    }
+}
+/**
+ * Wraps a `ReadableStreamDefaultReader<Uint8Array>` and provides a
+ * `next(count, timeoutMs)` method that accumulates bytes across calls,
+ * parses complete SSE event blocks, and returns the requested number of events.
+ *
+ * Comment lines (`:ping`) are silently skipped so heartbeats do not
+ * interfere with ordered event assertions.
+ */
+function createSseStreamReader(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    /**
+     * Parse all complete SSE event blocks currently in `buffer`.
+     * An event block is terminated by `\n\n`. Updates `buffer` in-place
+     * and returns the parsed events (skipping comment-only blocks).
+     */
+    function drainEvents() {
+        const events = [];
+        while (true) {
+            const blockEnd = buffer.indexOf("\n\n");
+            if (blockEnd === -1) {
+                break;
+            }
+            const block = buffer.slice(0, blockEnd);
+            buffer = buffer.slice(blockEnd + 2);
+            let eventName;
+            let dataLine;
+            for (const line of block.split("\n")) {
+                if (line.startsWith(":")) {
+                    // SSE comment — skip (heartbeat pings arrive as `:ping`)
+                    continue;
+                }
+                if (line.startsWith("event:")) {
+                    eventName = line.slice("event:".length).trim();
+                }
+                else if (line.startsWith("data:")) {
+                    dataLine = line.slice("data:".length).trim();
+                }
+            }
+            // Skip blocks that contained only comments (no data line).
+            if (dataLine === undefined) {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(dataLine);
+            }
+            catch {
+                parsed = dataLine;
+            }
+            events.push({ eventName, data: parsed, raw: dataLine });
+        }
+        return events;
+    }
+    /**
+     * Read until `count` SSE events have been accumulated or `timeoutMs`
+     * elapses (default 5 000 ms). Returns the collected events in order.
+     */
+    async function next(count = 1, timeoutMs = 5_000) {
+        const collected = [];
+        const deadline = Date.now() + timeoutMs;
+        // Drain whatever is already buffered before issuing new reads.
+        collected.push(...drainEvents());
+        while (collected.length < count) {
+            if (Date.now() >= deadline) {
+                throw new Error(`SSE reader timed out after ${timeoutMs} ms waiting for ${count} event(s); ` +
+                    `received ${collected.length} so far.`);
+            }
+            const remaining = deadline - Date.now();
+            const readResult = await Promise.race([
+                reader.read(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`SSE read timed out after ${timeoutMs} ms`)), remaining)),
+            ]);
+            if (readResult.done) {
+                break;
+            }
+            buffer += decoder.decode(readResult.value, { stream: true });
+            collected.push(...drainEvents());
+        }
+        return collected.slice(0, count);
+    }
+    async function cancel() {
+        await reader.cancel();
+    }
+    return { next, cancel };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+test("SSE wire: /stream returns text/event-stream and a connected event with connectionId", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const res = await fetch(`${baseUrl}/stream`, {
+            headers: { Authorization: authHeader },
+        });
+        assert.equal(res.status, 200, "HTTP status should be 200");
+        assert.ok(res.headers.get("content-type")?.includes("text/event-stream"), `Content-Type should include text/event-stream, got: ${res.headers.get("content-type")}`);
+        assert.ok(res.body, "Response body should be a readable stream");
+        const reader = createSseStreamReader(res.body);
+        try {
+            const events = await reader.next(1);
+            assert.equal(events.length, 1, "Should receive exactly 1 event");
+            const data = events[0]?.data;
+            assert.equal(data.type, "connected", `type should be "connected", got: ${data.type}`);
+            assert.ok(typeof data.connectionId === "string" && data.connectionId.startsWith("web-"), `connectionId should be a string starting with "web-", got: ${data.connectionId}`);
+        }
+        finally {
+            await reader.cancel();
+        }
+    });
+});
+test("SSE wire: /api/cancel broadcasts a cancelled event with sessionKey to connected clients", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const res = await fetch(`${baseUrl}/stream`, {
+            headers: { Authorization: authHeader },
+        });
+        assert.ok(res.body, "Response body should be a readable stream");
+        const reader = createSseStreamReader(res.body);
+        try {
+            // Drain the initial connected event.
+            const connected = await reader.next(1);
+            assert.equal(connected[0]?.data?.type, "connected", "First event should be connected");
+            // POST cancel — broadcasts a cancelled event to all SSE clients.
+            const cancelRes = await fetch(`${baseUrl}/api/cancel`, {
+                method: "POST",
+                headers: { Authorization: authHeader },
+            });
+            assert.equal(cancelRes.status, 200, "Cancel should return 200");
+            // Read the next event off the same open connection.
+            const events = await reader.next(1);
+            assert.equal(events.length, 1, "Should receive 1 event after cancel");
+            const data = events[0]?.data;
+            assert.equal(data.type, "cancelled", `type should be "cancelled", got: ${data.type}`);
+            assert.ok(typeof data.sessionKey === "string" && data.sessionKey.length > 0, `sessionKey should be a non-empty string, got: ${JSON.stringify(data.sessionKey)}`);
+        }
+        finally {
+            await reader.cancel();
+        }
+    });
+});
+test("SSE wire: cancel event is broadcast to all concurrent subscribers with matching sessionKey", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        // Open two simultaneous SSE connections.
+        const [res1, res2] = await Promise.all([
+            fetch(`${baseUrl}/stream`, { headers: { Authorization: authHeader } }),
+            fetch(`${baseUrl}/stream`, { headers: { Authorization: authHeader } }),
+        ]);
+        assert.ok(res1.body, "Connection 1 should have a readable body");
+        assert.ok(res2.body, "Connection 2 should have a readable body");
+        const reader1 = createSseStreamReader(res1.body);
+        const reader2 = createSseStreamReader(res2.body);
+        try {
+            // Drain the connected events from both connections.
+            const [conn1, conn2] = await Promise.all([reader1.next(1), reader2.next(1)]);
+            assert.equal(conn1[0]?.data?.type, "connected", "Connection 1 first event should be connected");
+            assert.equal(conn2[0]?.data?.type, "connected", "Connection 2 first event should be connected");
+            // POST cancel — should broadcast to both subscribers.
+            const cancelRes = await fetch(`${baseUrl}/api/cancel`, {
+                method: "POST",
+                headers: { Authorization: authHeader },
+            });
+            assert.equal(cancelRes.status, 200, "Cancel should return 200");
+            // Both readers should receive the cancelled event.
+            const [events1, events2] = await Promise.all([reader1.next(1), reader2.next(1)]);
+            const data1 = events1[0]?.data;
+            const data2 = events2[0]?.data;
+            assert.equal(data1.type, "cancelled", `Connection 1 type should be "cancelled"`);
+            assert.equal(data2.type, "cancelled", `Connection 2 type should be "cancelled"`);
+            assert.ok(typeof data1.sessionKey === "string" && data1.sessionKey.length > 0, `Connection 1 sessionKey should be a non-empty string, got: ${JSON.stringify(data1.sessionKey)}`);
+            assert.ok(typeof data2.sessionKey === "string" && data2.sessionKey.length > 0, `Connection 2 sessionKey should be a non-empty string, got: ${JSON.stringify(data2.sessionKey)}`);
+            assert.equal(data1.sessionKey, data2.sessionKey, `Both connections must receive the same sessionKey; ` +
+                `got "${data1.sessionKey}" vs "${data2.sessionKey}"`);
+        }
+        finally {
+            await Promise.all([reader1.cancel(), reader2.cancel()]);
+        }
+    });
+});
+//# sourceMappingURL=sse.integration.test.js.map

package/dist/api/sse.js

@@ -0,0 +1,7 @@
+export function formatSseData(payload) {
+    return `data: ${JSON.stringify(payload)}\n\n`;
+}
+export function formatSseEvent(eventName, payload) {
+    return `event: ${eventName}\ndata: ${JSON.stringify(payload)}\n\n`;
+}
+//# sourceMappingURL=sse.js.map