@harness-fe/mcp-server 3.0.1 → 3.2.0

package/README.md

@@ -123,6 +123,70 @@ Matching env vars: `HARNESS_FE_HOST`, `HARNESS_FE_PORT`,
 `HARNESS_FE_TOKEN`, `HARNESS_FE_MCP_TRANSPORT`, `HARNESS_FE_MCP_PATH`,
 `HARNESS_FE_HEADLESS`.
 
+## Embedding into a host app
+
+For most users, running the CLI as a separate process is the right call.
+If you're shipping your **own** product and want the harness daemon to live
+inside *your* Node process — sharing your auth, your storage, your lifecycle
+— use `createDaemon`:
+
+```ts
+import { createDaemon } from '@harness-fe/mcp-server';
+
+const daemon = createDaemon({
+    port: 47730,                       // pick a port distinct from devs' local 47729
+    host: '127.0.0.1',
+    authorize: (req) => verifyMyJwt(req.headers.authorization), // your auth
+    label: 'my-app',
+});
+
+await daemon.start();
+process.on('SIGTERM', () => daemon.stop());
+```
+
+That call starts the WS bridge **and** mounts the MCP HTTP transport at
+`/mcp` on the daemon's own listener. The CLI uses the same factory under
+the hood — there is exactly one boot path.
+
+### Picking the right options
+
+| Option | When to use |
+|---|---|
+| `authorize: (req) => boolean` | You already have an auth layer (JWT, session cookie, etc.). Return `true` to accept the request. The built-in token check is skipped. |
+| `token: 'xxxx'` | You want the built-in token gate. Mutually exclusive with `authorize`. Same wire conventions as the CLI's `--token`. |
+| `store`, `taskStore`, `memoryStore` | Plug in custom `IStore` implementations to land data in your own DB instead of `~/.harness/`. Pass `null` to disable persistence entirely. |
+| `eventStore` | Custom SSE `EventStore` for resumable streaming. Omit for the in-memory default; pass `null` to disable Last-Event-ID resumption. |
+| `mcpHttp: false` | Boot only the WS bridge; skip mounting `/mcp`. Use when you want to wire MCP through stdio yourself (this is how the CLI's stdio mode embeds the daemon). |
+| `mcpPath: '/agents/mcp'` | Move the MCP HTTP endpoint to a non-default path. |
+| `dataDir` | Override the on-disk root for default JSONL stores. |
+
+### Resumable SSE
+
+The MCP HTTP transport supports `Last-Event-ID` reconnection out of the
+box. Long agent runs survive transient network drops — when a client
+reconnects with the `Last-Event-ID` header, the server replays every
+event past that id with no duplicates and no gaps.
+
+Defaults: in-memory ring with 1000 events / 5 minutes / 50 MiB cap per
+stream. Override with `eventStore: new MemoryEventStore({...})` or plug
+in your own backend. Set `eventStore: null` to opt out.
+
+### Working example
+
+A self-contained example lives at
+[`examples/embed-express/`](https://github.com/Morphicai/harness-fe/tree/main/packages/mcp-server/examples/embed-express):
+an Express app and the harness daemon share one Node process, with a
+custom `authorize` hook standing in for the host's real auth.
+
+### Embedding vs running the CLI: which?
+
+- **CLI** is right for development. Devs run `npx @harness-fe/mcp-server`
+  alongside their dev server; AI agents (Claude Code / Cursor / Kiro)
+  speak to it over stdio MCP. **The CLI is what 99% of users want.**
+- **`createDaemon`** is right when your *product* embeds the harness —
+  for example, a hosted dev environment that runs the daemon under its
+  own auth so users don't have to install or configure anything.
+
 ## What it exposes
 
 Tools across these domains (see [Architecture](https://github.com/Morphicai/harness-fe/blob/main/ARCHITECTURE.md)):

package/dist/cli.js

@@ -17,10 +17,10 @@
  */
 import { randomBytes } from 'node:crypto';
 import { DEFAULT_HOST, DEFAULT_WS_PORT, buildHttpUrl, isLoopbackHost, parseWsUrl, } from '@harness-fe/protocol';
-import { Bridge, defaultDataDir } from './bridge.js';
+import { defaultDataDir } from './bridge.js';
+import { createDaemon } from './daemon.js';
 import { RemoteBridge } from './remoteBridge.js';
 import { startMcpStdioServer } from './mcp.js';
-import { startMcpHttpServer } from './mcpHttp.js';
 function printHelpAndExit() {
     const help = `harness-fe — frontend harness MCP daemon
 
@@ -211,30 +211,24 @@ async function main() {
     validate(cfg);
     const { active, shutdown, role } = await startBridgeOrAttach(cfg);
     printBanner(cfg, role, active.getViewerBaseUrl());
-    let mcpShutdown;
     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. ' +
                 'Another daemon already holds the port; stop it first.\n');
             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);
     };
@@ -242,25 +236,33 @@ async function main() {
     process.on('SIGTERM', onSignal);
 }
 async function startBridgeOrAttach(cfg) {
-    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 = 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?.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.
     const remote = new RemoteBridge({ port: cfg.port, host: cfg.host, token: cfg.token });

package/dist/daemon.d.ts

@@ -43,8 +43,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.
@@ -76,6 +87,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 {
     /**

package/dist/daemon.js

@@ -26,6 +26,15 @@ import { Bridge } from './bridge.js';
 import { startMcpHttpServer } from './mcpHttp.js';
 export function createDaemon(opts = {}) {
     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,
         host: opts.host,
@@ -35,7 +44,7 @@ export function createDaemon(opts = {}) {
         memoryStore: opts.memoryStore,
         dataDir: opts.dataDir,
         label: opts.label,
-        auth: opts.authorize ? { authorize: opts.authorize } : undefined,
+        auth,
     });
     let mcpHandle;
     let started = false;
@@ -48,13 +57,15 @@ export function createDaemon(opts = {}) {
                 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() {
             if (stopped)

package/dist/mcp.js

@@ -10,6 +10,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { COMMAND, PROTOCOL_VERSION, clickArgsSchema, evaluateArgsSchema, navigateArgsSchema, reloadArgsSchema, screenshotArgsSchema, scrollArgsSchema, setHtmlArgsSchema, setStyleArgsSchema, selectorSchema, typeArgsSchema, waitForArgsSchema, } from '@harness-fe/protocol';
 import { RemoteBridge } from './remoteBridge.js';
+import { buildVisitorTimeline } from './visitorTimeline.js';
 import { createReplayExport } from './replayCreate.js';
 import { openBrowser } from './openBrowser.js';
 import { buildDashboardUrl } from './dashboardUrl.js';
@@ -203,35 +204,162 @@ function registerTools(server, bridge) {
         const out = await bridge.sendCommand(COMMAND.PAGE_SET_STYLE, args, { tabId });
         return ok(out);
     });
+    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);
     });
     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 }) => {
-        const out = await bridge.sendCommand(COMMAND.NETWORK_TAIL, { n: n ?? 20, includeBody: includeBody ?? false }, { tabId });
+    }, async ({ n, includeBody, filter, match, urlContains, method, statusCode, tabId }) => {
+        const out = await bridge.sendCommand(COMMAND.NETWORK_TAIL, { n: n ?? 20, includeBody: includeBody ?? false, filter, match, urlContains, method, statusCode }, { tabId });
         return ok(out);
     });
     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, tabId }) => {
-        const out = await bridge.sendCommand(COMMAND.ERRORS_TAIL, { n: n ?? 20 }, { tabId });
+    }, 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, 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);
     });
     server.registerTool(COMMAND.TAB_LIST, {
@@ -394,7 +522,7 @@ function registerStoreTools(server, store, memoryStore, bridge) {
         return ok(summary);
     });
     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(),
@@ -562,6 +690,29 @@ function registerStoreTools(server, store, memoryStore, bridge) {
         const slice = limit ? sessionsOut.slice(0, limit) : sessionsOut;
         return ok({ visitor, sessions: slice });
     });
+    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', {
         description: 'List rrweb recording chunks available for a session.',
         inputSchema: {
@@ -727,7 +878,7 @@ function registerRemoteStoreTools(server, bridge) {
         return ok(summary);
     });
     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/dist/store/types.d.ts

@@ -19,7 +19,7 @@
 import type { Task, VisitorEnv } from '@harness-fe/protocol';
 export type { EventId, EventStore, StreamId, } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 /** Short type codes used in JSONL lines to keep files compact. */
-export type EventType = 'log' | 'err' | 'req' | 'res' | 'cmd' | 'resp' | 'hmr' | 'task' | 'task:claim' | 'task:resolve' | 'rrweb' | 'node:log' | 'node:err' | 'note' | 'load' | 'storage' | 'server-log' | 'server-err' | 'server-action' | 'app-log' | string;
+export type EventType = 'log' | 'err' | 'req' | 'res' | 'cmd' | 'resp' | 'hmr' | 'task' | 'task:claim' | 'task:resolve' | 'rrweb' | 'node:log' | 'node:err' | 'note' | 'load' | 'storage' | 'ws' | 'navigation' | 'globals' | 'indexeddb' | 'server-log' | 'server-err' | 'server-action' | 'app-log' | string;
 /** A single event line in a JSONL file. Carries row-level projectId/buildId tags. */
 export interface StoreEvent {
     /**

package/dist/visitorTimeline.d.ts

@@ -0,0 +1,24 @@
+/**
+ * visitor.timeline — merge event timelines across all sessions belonging to
+ * one visitor. Pulled out of mcp.ts so the merge / filter logic is unit
+ * testable without spinning up an McpServer.
+ */
+import type { IStore, StoreEvent } from './store/index.js';
+export interface VisitorTimelineOptions {
+    since?: number;
+    until?: number;
+    types?: string | string[];
+    tabIds?: string[];
+    sessionIds?: string[];
+    limit?: number;
+}
+export interface VisitorTimelineResult {
+    visitorId: string;
+    sessionCount: number;
+    eventCount: number;
+    truncated: boolean;
+    events: StoreEvent[];
+}
+export declare function buildVisitorTimeline(store: IStore, visitorId: string, opts?: VisitorTimelineOptions): VisitorTimelineResult | {
+    error: string;
+};

package/dist/visitorTimeline.js

@@ -0,0 +1,68 @@
+/**
+ * visitor.timeline — merge event timelines across all sessions belonging to
+ * one visitor. Pulled out of mcp.ts so the merge / filter logic is unit
+ * testable without spinning up an McpServer.
+ */
+const DEFAULT_LIMIT = 200;
+const SESSION_DISCOVERY_PAGE = 200;
+export function buildVisitorTimeline(store, visitorId, opts = {}) {
+    const visitor = store.getVisitor(visitorId);
+    if (!visitor)
+        return { error: `visitor not found: ${visitorId}` };
+    const cap = opts.limit ?? DEFAULT_LIMIT;
+    const tabFilter = opts.tabIds && opts.tabIds.length > 0 ? new Set(opts.tabIds) : undefined;
+    // 1. Discover candidate sessions (or honor the explicit list).
+    const candidateIds = new Set();
+    if (opts.sessionIds && opts.sessionIds.length > 0) {
+        for (const id of opts.sessionIds)
+            candidateIds.add(id);
+    }
+    else {
+        const visitorTabs = new Set(visitor.tabIds);
+        for (const pid of visitor.projectIds) {
+            for (const sess of store.listSessions({ projectId: pid, limit: SESSION_DISCOVERY_PAGE })) {
+                if (candidateIds.has(sess.id))
+                    continue;
+                if (sess.tabId && !visitorTabs.has(sess.tabId))
+                    continue;
+                if (tabFilter && sess.tabId && !tabFilter.has(sess.tabId))
+                    continue;
+                candidateIds.add(sess.id);
+            }
+        }
+    }
+    // 2. Pull tail() from each session and merge. Over-fetch by 1 per session
+    //    so we can detect single-session truncation (tail returns exactly `cap`
+    //    when there are more, indistinguishable from "the session had exactly
+    //    `cap` events" otherwise).
+    const merged = [];
+    let perSessionTruncated = false;
+    for (const sid of candidateIds) {
+        const events = store.tail(sid, {
+            n: cap + 1,
+            type: opts.types,
+            since: opts.since,
+            until: opts.until,
+        });
+        if (events.length > cap)
+            perSessionTruncated = true;
+        for (const ev of events) {
+            if (ev.visitorId && ev.visitorId !== visitorId)
+                continue;
+            if (tabFilter && ev.tab && !tabFilter.has(ev.tab))
+                continue;
+            merged.push(ev);
+        }
+    }
+    // 3. Ascending sort, then trim to the newest `cap` events.
+    merged.sort((a, b) => a.ts - b.ts);
+    const truncated = perSessionTruncated || merged.length > cap;
+    const slice = merged.length > cap ? merged.slice(merged.length - cap) : merged;
+    return {
+        visitorId,
+        sessionCount: candidateIds.size,
+        eventCount: slice.length,
+        truncated,
+        events: slice,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/mcp-server",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Unified MCP daemon: stdio MCP for AI agents + WS bridge for Vite plugin and runtime client.",
   "type": "module",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "rrweb-player": "1.0.0-alpha.4",
     "ws": "^8.18.0",
     "zod": "^4.4.3",
-    "@harness-fe/protocol": "3.0.0",
-    "@harness-fe/dashboard-ui": "0.2.0"
+    "@harness-fe/dashboard-ui": "0.2.0",
+    "@harness-fe/protocol": "3.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.10",