@harness-fe/mcp-server 3.0.1 → 3.2.0

package/src/cli.ts

@@ -24,10 +24,10 @@ import {
     isLoopbackHost,
     parseWsUrl,
 } from '@harness-fe/protocol';
-import { Bridge, defaultDataDir, type IBridge } from './bridge.js';
+import { defaultDataDir, type IBridge } from './bridge.js';
+import { createDaemon, type DaemonHandle } from './daemon.js';
 import { RemoteBridge } from './remoteBridge.js';
 import { startMcpStdioServer } from './mcp.js';
-import { startMcpHttpServer } from './mcpHttp.js';
 
 type McpTransport = 'stdio' | 'http';
 
@@ -247,11 +247,13 @@ async function main() {
     const { active, shutdown, role } = await startBridgeOrAttach(cfg);
     printBanner(cfg, role, active.getViewerBaseUrl());
 
-    let mcpShutdown: (() => Promise<void>) | undefined;
     if (cfg.mcpTransport === 'stdio') {
         await startMcpStdioServer(active);
         process.stderr.write('[harness-fe] MCP stdio server connected\n');
     } else {
+        // HTTP transport: the leader's createDaemon() call already mounted
+        // /mcp via mcpHttp:true. Followers fall through here with no leader
+        // attached, so HTTP mode is unsupported for them.
         if (role === 'follower') {
             process.stderr.write(
                 '[harness-fe] --mcp-transport=http is only supported on the leader. ' +
@@ -260,16 +262,11 @@ async function main() {
             await shutdown();
             process.exit(2);
         }
-        const handle = await startMcpHttpServer(active, { path: cfg.mcpPath });
-        process.stderr.write(`[harness-fe] MCP http server mounted at ${handle.path}\n`);
-        mcpShutdown = () => handle.close();
+        process.stderr.write(`[harness-fe] MCP http server mounted at ${cfg.mcpPath}\n`);
     }
 
     const onSignal = async () => {
         process.stderr.write('[harness-fe] shutting down\n');
-        if (mcpShutdown) {
-            try { await mcpShutdown(); } catch { /* swallow */ }
-        }
         await shutdown();
         process.exit(0);
     };
@@ -280,23 +277,31 @@ async function main() {
 async function startBridgeOrAttach(
     cfg: CliConfig,
 ): Promise<{ active: IBridge; shutdown: () => Promise<void>; role: 'leader' | 'follower' }> {
-    const bridge = new Bridge({
+    // Leader path: use createDaemon so there's exactly one boot path between
+    // the CLI and any host application that embeds the daemon. The factory
+    // mounts /mcp itself when mcpHttp:true, so we don't need to call
+    // startMcpHttpServer here.
+    const daemon: DaemonHandle = createDaemon({
         port: cfg.port,
         host: cfg.host,
         dataDir: cfg.dataDir,
         label: cfg.label,
-        auth: cfg.token ? { token: cfg.token } : undefined,
+        token: cfg.token,
         publicHost: cfg.publicHost,
+        mcpHttp: cfg.mcpTransport === 'http',
+        mcpPath: cfg.mcpPath,
     });
     try {
-        await bridge.start();
+        await daemon.start();
         return {
-            active: bridge,
-            shutdown: () => bridge.stop(),
+            active: daemon.bridge,
+            shutdown: () => daemon.stop(),
             role: 'leader',
         };
     } catch (err) {
         if ((err as NodeJS.ErrnoException)?.code !== 'EADDRINUSE') throw err;
+        // Factory's bridge.start failed on EADDRINUSE; the factory itself
+        // didn't mount anything else, so there's nothing further to clean up.
     }
 
     // Port already taken — attach as follower.

package/src/daemon.ts

@@ -47,8 +47,19 @@ export interface DaemonOptions {
      * skipped — there is exactly one auth pipeline. Synchronous because the
      * WS upgrade handshake completes inline; async auth should be cached in
      * a cookie by the host's own middleware and read back here.
+     *
+     * Mutually exclusive with `token`. If both are provided, `authorize`
+     * wins and `token` is ignored.
      */
     authorize?: (req: IncomingMessage) => boolean;
+    /**
+     * Static token; auth requires `Authorization: Bearer <token>`, the
+     * `harness_fe_token` cookie, `?token=<token>`, or the matching WS
+     * subprotocol. Use this when you want the daemon's built-in auth and
+     * have no reason to plug in custom logic — the CLI's `--token` flag
+     * flows through here. Mutually exclusive with `authorize`.
+     */
+    token?: string;
     /**
      * IStore implementation. Omit for the default JSONL store at `dataDir`.
      * Pass `null` to disable session/event persistence entirely.
@@ -80,6 +91,14 @@ export interface DaemonOptions {
      * Claude Code, Cursor, and the MCP spec default expect).
      */
     mcpStateful?: boolean;
+    /**
+     * Whether to mount the MCP HTTP Streamable transport at `mcpPath`.
+     * Default `true`. Set to `false` if the host only needs the WS bridge
+     * (and wires up MCP over stdio externally — that's how the CLI's
+     * stdio mode boots the daemon through this factory without also
+     * exposing an HTTP MCP endpoint).
+     */
+    mcpHttp?: boolean;
 }
 
 export interface DaemonHandle {
@@ -103,6 +122,16 @@ export interface DaemonHandle {
 
 export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
     const mcpPath = opts.mcpPath ?? '/mcp';
+    const mountMcpHttp = opts.mcpHttp ?? true;
+
+    // Resolve auth: authorize wins if both are set. `undefined` here means
+    // no auth at all (loopback dev default). One pipeline — Bridge sees
+    // exactly one of `{ authorize }`, `{ token }`, or nothing.
+    const auth = opts.authorize
+        ? { authorize: opts.authorize }
+        : opts.token
+            ? { token: opts.token }
+            : undefined;
 
     const bridge = new Bridge({
         port: opts.port,
@@ -113,7 +142,7 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
         memoryStore: opts.memoryStore,
         dataDir: opts.dataDir,
         label: opts.label,
-        auth: opts.authorize ? { authorize: opts.authorize } : undefined,
+        auth,
     });
 
     let mcpHandle: Awaited<ReturnType<typeof startMcpHttpServer>> | undefined;
@@ -128,13 +157,15 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
             if (started) return;
             started = true;
             await bridge.start();
-            // Forward eventStore as-is so `null` opts out of resumability and
-            // `undefined` falls through to the default MemoryEventStore.
-            mcpHandle = await startMcpHttpServer(bridge, {
-                path: mcpPath,
-                stateful: opts.mcpStateful,
-                eventStore: opts.eventStore,
-            });
+            if (mountMcpHttp) {
+                // Forward eventStore as-is so `null` opts out of resumability and
+                // `undefined` falls through to the default MemoryEventStore.
+                mcpHandle = await startMcpHttpServer(bridge, {
+                    path: mcpPath,
+                    stateful: opts.mcpStateful,
+                    eventStore: opts.eventStore,
+                });
+            }
         },
 
         async stop() {

package/src/mcp.ts

@@ -28,6 +28,7 @@ import type { IBridge } from './bridge.js';
 import type { Bridge } from './bridge.js';
 import { RemoteBridge } from './remoteBridge.js';
 import type { IStore, IMemoryStore } from './store/index.js';
+import { buildVisitorTimeline } from './visitorTimeline.js';
 import { createReplayExport } from './replayCreate.js';
 import { openBrowser } from './openBrowser.js';
 import { buildDashboardUrl } from './dashboardUrl.js';
@@ -308,17 +309,27 @@ function registerTools(server: McpServer, bridge: IBridge): void {
         },
     );
 
+    const filterParam = z.string().optional().describe('Substring or regex (see `match`). Filters entries by their serialized payload before return.');
+    const matchParam = z.enum(['contains', 'regex']).optional().describe('How to interpret `filter`. Default: contains (case-insensitive). regex is case-insensitive too.');
+
     server.registerTool(
         COMMAND.CONSOLE_TAIL,
         {
-            description: 'Return the last N console entries from the page.',
+            description: 'Return the last N console entries from the page. Pass `filter` for substring/regex match against {level, args}; `level` for an exact match. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["log"]) for cross-navigate history.',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                level: z.enum(['log', 'info', 'warn', 'error', 'debug']).optional(),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, tabId }) => {
-            const out = await bridge.sendCommand(COMMAND.CONSOLE_TAIL, { n: n ?? 20 }, { tabId });
+        async ({ n, filter, match, level, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.CONSOLE_TAIL,
+                { n: n ?? 20, filter, match, level },
+                { tabId },
+            );
             return ok(out);
         },
     );
@@ -326,17 +337,22 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     server.registerTool(
         COMMAND.NETWORK_TAIL,
         {
-            description: 'Return the last N network requests captured by the runtime client.',
+            description: 'Return the last N network requests captured by the runtime client. Each entry has phase=req|res keyed by `id`, and (for requests) an `initiator.stack` so you can see which code issued the call. Pass `filter` (against {url, method, body}), or narrow via `urlContains` / `method` / `statusCode`. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["req","res"]) for cross-navigate history.',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
                 includeBody: z.boolean().optional(),
+                filter: filterParam,
+                match: matchParam,
+                urlContains: z.string().optional().describe('Substring filter on url (case-sensitive).'),
+                method: z.string().optional().describe('Exact HTTP method match (e.g. "POST"). Case-insensitive.'),
+                statusCode: z.number().int().optional().describe('Exact status code match (response entries only).'),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, includeBody, tabId }) => {
+        async ({ n, includeBody, filter, match, urlContains, method, statusCode, tabId }) => {
             const out = await bridge.sendCommand(
                 COMMAND.NETWORK_TAIL,
-                { n: n ?? 20, includeBody: includeBody ?? false },
+                { n: n ?? 20, includeBody: includeBody ?? false, filter, match, urlContains, method, statusCode },
                 { tabId },
             );
             return ok(out);
@@ -346,14 +362,217 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     server.registerTool(
         COMMAND.ERRORS_TAIL,
         {
-            description: 'Return the last N JavaScript errors captured by the runtime client.',
+            description: 'Return the last N JavaScript errors captured by the runtime client. Pass `filter` for substring/regex match against {message, stack, source}. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["err"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.ERRORS_TAIL,
+                { n: n ?? 20, filter, match },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.WS_TAIL,
+        {
+            description:
+                'Return the last N WebSocket frames captured by the runtime client. Each entry has phase=open|send|recv|close, a stable id per connection, payload (text/JSON when possible, [binary Nb] for buffers), and initiator.stack on open/send so you can see which code opened the connection or sent the frame. Pass `filter` for substring/regex match against {url, payload, reason}; `phase` for an exact match. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["ws"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                phase: z.enum(['open', 'send', 'recv', 'close']).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, phase, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.WS_TAIL,
+                { n: n ?? 20, filter, match, phase },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_WAIT_FOR,
+        {
+            description:
+                'Resolve when a network request matching the predicate happens (or rejects on timeout). Considers requests issued AFTER this call — pre-existing matches in the buffer do not satisfy the wait.',
+            inputSchema: {
+                urlContains: z.string().optional(),
+                urlRegex: z.string().optional().describe('Case-insensitive regex against url.'),
+                method: z.string().optional(),
+                statusCode: z.number().int().optional(),
+                timeoutMs: z.number().int().positive().default(10000).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ urlContains, urlRegex, method, statusCode, timeoutMs, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.NETWORK_WAIT_FOR,
+                { urlContains, urlRegex, method, statusCode, timeoutMs },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_WAIT_FOR_IDLE,
+        {
+            description:
+                'Resolve when no new network entries arrived for `idleMs` (default 500ms) — analogous to Playwright `waitForLoadState("networkidle")`. Useful for sequencing actions after a navigation or interaction.',
+            inputSchema: {
+                idleMs: z.number().int().positive().default(500).optional(),
+                timeoutMs: z.number().int().positive().default(10000).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ idleMs, timeoutMs, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.NETWORK_WAIT_FOR_IDLE,
+                { idleMs, timeoutMs },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_GET,
+        {
+            description:
+                'Return all entries (req + res) for a single network request id. Use after `network.tail` when you need the full request/response body without the truncation pressure that comes from a multi-entry response.',
+            inputSchema: {
+                reqId: z.string().describe('id field from a `network.tail` entry'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ reqId, tabId }) => {
+            const out = await bridge.sendCommand(COMMAND.NETWORK_GET, { reqId }, { tabId });
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.WS_GET,
+        {
+            description:
+                'Return all frames (open / send / recv / close) for a single WebSocket id. Use after `ws.tail` when you need the full session of a particular connection.',
+            inputSchema: {
+                wsId: z.string().describe('id field from a `ws.tail` entry'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ wsId, tabId }) => {
+            const out = await bridge.sendCommand(COMMAND.WS_GET, { wsId }, { tabId });
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.STORAGE_TAIL,
+        {
+            description:
+                'Return the last N localStorage / sessionStorage / cookie mutations. Each entry has op=set|remove|clear, which=local|session|cookie, key/value, an `initiator.stack` showing who issued the write, and crossTab=true when the mutation arrived via the native storage event from another tab. Filter via `filter` (against {op, which, key, value}), or narrow with `which` / `op` / `key`. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["storage"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                which: z.enum(['local', 'session', 'cookie']).optional(),
+                op: z.enum(['set', 'remove', 'clear']).optional(),
+                key: z.string().optional().describe('Exact key match (case-sensitive).'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, which, op, key, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.STORAGE_TAIL,
+                { n: n ?? 20, filter, match, which, op, key },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NAVIGATION_TAIL,
+        {
+            description:
+                'Return the last N navigation events captured by the runtime: history.pushState / replaceState, popstate, hashchange, and location.href / location.hash / location.assign() / location.replace(). Each entry has `kind`, `url`, `replace`, and an `initiator.stack` for interceptable kinds. Filter via `filter` (against {kind, url, replace}) or narrow with `kind`. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["navigation"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                kind: z.enum(['push', 'replace', 'pop', 'hash', 'assign']).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, kind, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.NAVIGATION_TAIL,
+                { n: n ?? 20, filter, match, kind },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.GLOBALS_TAIL,
+        {
+            description:
+                'Return the last N read/writes to watched window globals. Only fires for keys registered via the install opts `globals.watch` list — global pollution detection or app-state debugging. Each entry has op=get|set|delete, key, value, previousValue (on set), and initiator.stack. Filter via `filter` or narrow with `op` / `key`. Buffer is in-memory; cross-navigate use `session.tail` (type=["globals"]).',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                op: z.enum(['get', 'set', 'delete']).optional(),
+                key: z.string().optional().describe('Exact window key match.'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, op, key, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.GLOBALS_TAIL,
+                { n: n ?? 20, filter, match, op, key },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.INDEXEDDB_TAIL,
+        {
+            description:
+                'Return the last N IndexedDB operations: open / put / add / get / getAll / delete / clear / cursor. Each entry has `op`, `store`, `key`, `value`, `db`, `version`, `success` and `initiator.stack`. Useful for tracking who reads/writes which IDB store key. Filter via `filter` (against {op, store, key}) or narrow with `op` / `store` / `db`. Buffer is in-memory; cross-navigate use `session.tail` (type=["indexeddb"]).',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                op: z.enum(['open', 'put', 'add', 'get', 'getAll', 'delete', 'clear', 'cursor']).optional(),
+                store: z.string().optional().describe('Exact object-store name.'),
+                db: z.string().optional().describe('Exact database name (open events only).'),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, tabId }) => {
-            const out = await bridge.sendCommand(COMMAND.ERRORS_TAIL, { n: n ?? 20 }, { tabId });
+        async ({ n, filter, match, op, store, db, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.INDEXEDDB_TAIL,
+                { n: n ?? 20, filter, match, op, store, db },
+                { tabId },
+            );
             return ok(out);
         },
     );
@@ -602,7 +821,7 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
     server.registerTool(
         'session.tail',
         {
-            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId.',
+            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId. For cross-tab debugging within one visitor, use `visitor.timeline` to merge multiple sessions.',
             inputSchema: {
                 sessionId: z.string(),
                 n: z.number().int().positive().default(50).optional(),
@@ -840,6 +1059,34 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
         },
     );
 
+    server.registerTool(
+        'visitor.timeline',
+        {
+            description:
+                'Merged event timeline across all sessions for one visitor, ascending by ts. Use this for cross-tab debugging (e.g. a ws frame in tab A causing a storage write in tab B). Each event carries `sessionId` and `tab` so the source tab is visible. Pass `sessionIds` to skip auto-discovery and merge a known set.',
+            inputSchema: {
+                visitorId: z.string(),
+                since: z.number().optional().describe('Only events after this Unix ts (ms)'),
+                until: z.number().optional().describe('Only events before this Unix ts (ms)'),
+                types: z.union([z.string(), z.array(z.string())]).optional()
+                    .describe('Filter by event type(s): log, err, req, res, ws, storage, cmd, resp, ...'),
+                tabIds: z.array(z.string()).optional()
+                    .describe('Narrow merge to specific tabIds. Default: all tabs known to this visitor.'),
+                sessionIds: z.array(z.string()).optional()
+                    .describe('Explicit session list to merge. When set, skips visitor → session discovery.'),
+                limit: z.number().int().positive().optional()
+                    .describe('Max events returned (newest). Default 200.'),
+            },
+        },
+        async ({ visitorId, since, until, types, tabIds, sessionIds, limit }) => {
+            const result = buildVisitorTimeline(store, visitorId, {
+                since, until, types, tabIds, sessionIds, limit,
+            });
+            if ('error' in result) return err(result.error);
+            return ok(result);
+        },
+    );
+
     server.registerTool(
         'session.recordings.list',
         {
@@ -1087,7 +1334,7 @@ function registerRemoteStoreTools(server: McpServer, bridge: RemoteBridge): void
     server.registerTool(
         'session.tail',
         {
-            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId.',
+            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId. For cross-tab debugging within one visitor, use `visitor.timeline` to merge multiple sessions.',
             inputSchema: {
                 sessionId: z.string(),
                 n: z.number().int().positive().default(50).optional(),

package/src/mcpHttp.test.ts

@@ -98,4 +98,106 @@ describe('mcpHttp', () => {
         // bodyless GET) means we made it past the auth layer.
         expect(withAuth.status).not.toBe(401);
     });
+
+    // SSE Last-Event-ID resumption — end-to-end wiring proof.
+    //
+    // What this asserts:
+    //   1. A real MCP HTTP session goes through the wire protocol cleanly.
+    //   2. The configured `EventStore` actually sees `storeEvent` calls
+    //      (the SDK is wired to persist outgoing messages through the
+    //      transport — not just sitting unused).
+    //   3. When a new GET arrives with `Last-Event-ID`, the SDK invokes
+    //      `replayEventsAfter` on the same store with that id (the resume
+    //      path is taken; replay isn't a no-op).
+    //
+    // The actual "no dupes / no gaps" invariant is covered comprehensively
+    // by MemoryEventStore.test.ts — here we prove the transport drives it.
+    it('drives the EventStore on stream and replays after Last-Event-ID', async () => {
+        const bridge = await startBridge();
+
+        // Spy that mirrors MemoryEventStore's contract while recording calls.
+        const storeCalls: Array<{ streamId: string; eventId: string }> = [];
+        const replayCalls: Array<{ lastEventId: string }> = [];
+        const eventsByStream = new Map<
+            string,
+            Array<{ eventId: string; message: JSONRPCMessage }>
+        >();
+        let seq = 0;
+        const spy: EventStore = {
+            async storeEvent(streamId, message) {
+                seq += 1;
+                const eventId = `${streamId}_${seq}`;
+                storeCalls.push({ streamId, eventId });
+                const arr = eventsByStream.get(streamId) ?? [];
+                arr.push({ eventId, message });
+                eventsByStream.set(streamId, arr);
+                return eventId;
+            },
+            async replayEventsAfter(lastEventId, { send }) {
+                replayCalls.push({ lastEventId });
+                // Recover streamId from event id and replay everything past it.
+                const streamId = lastEventId.split('_')[0];
+                const arr = eventsByStream.get(streamId) ?? [];
+                let resuming = false;
+                for (const { eventId, message } of arr) {
+                    if (resuming) await send(eventId, message);
+                    if (eventId === lastEventId) resuming = true;
+                }
+                return streamId;
+            },
+        };
+
+        const handle = await startMcpHttpServer(bridge, {
+            path: '/mcp',
+            eventStore: spy,
+        });
+        cleanups.push(() => handle.close());
+        const port = bridge.getBoundPort()!;
+        const url = `http://127.0.0.1:${port}/mcp`;
+
+        // 1. Initialize MCP session. The response goes back over the
+        //    Streamable HTTP response stream, so the SDK persists each
+        //    outgoing message through our spy store.
+        const init = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'mcpHttp.test', version: '0.0.0' },
+                },
+            }),
+        });
+        const sessionId = init.headers.get('mcp-session-id');
+        expect(sessionId).toBeTruthy();
+        // Drain the response body so the connection can be reused.
+        await init.text();
+
+        // 2. The SDK should have persisted at least one message to the
+        //    EventStore by now — the initialize response.
+        expect(storeCalls.length).toBeGreaterThan(0);
+        const firstEventId = storeCalls[0]!.eventId;
+
+        // 3. Reopen the stream with Last-Event-ID set. This is what a
+        //    real client would do after a transient disconnect.
+        const resumed = await fetch(url, {
+            headers: {
+                accept: 'text/event-stream',
+                'mcp-session-id': sessionId!,
+                'last-event-id': firstEventId,
+            },
+        });
+        // Status varies (200 SSE) but the salient assertion is the spy
+        // saw the replay path get hit with the same id we passed.
+        expect(replayCalls).toEqual([{ lastEventId: firstEventId }]);
+        // Drop the long-lived stream we just opened — it has no consumer.
+        await resumed.body?.cancel();
+    });
 });