@harness-fe/runtime 3.0.1 → 3.1.0

package/dist/wsPatch.js

@@ -0,0 +1,172 @@
+/**
+ * WebSocket monkey-patch — captures open / send / recv / close frames so
+ * agents can see long-lived push channels (IM, presence, sync, kick-out).
+ *
+ * Safety contract (mirrors fetchPatch):
+ *  1. Identity-preserving: replacement is a constructor with the same name,
+ *     prototype, and CONNECTING/OPEN/CLOSING/CLOSED static fields. Existing
+ *     `instanceof WebSocket` checks still pass because we extend the original.
+ *  2. Error-isolated: capture failures swallowed via safeEmit.
+ *  3. No timing or value change: pass-through to native WebSocket; we only
+ *     observe events and call sites. The original Promise / data flow is
+ *     untouched.
+ *  4. Bounded memory: frame payloads capped at BODY_CAP per send/recv. Binary
+ *     frames record a `[binary Nb]` marker rather than the bytes.
+ *
+ * The patch is idempotent. Returns a dispose function that restores
+ * `window.WebSocket`.
+ */
+import { captureInitiator } from './initiator.js';
+const DEFAULT_BODY_CAP = 256 * 1024;
+const PATCHED_FLAG = '__hfeWsPatched';
+const DEFAULT_DENYLIST = [/\/__hfe\//, /sockjs-node/];
+export function installWsPatch(opts) {
+    if (typeof window === 'undefined' || typeof window.WebSocket !== 'function') {
+        return () => { };
+    }
+    const OriginalWS = window.WebSocket;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (OriginalWS[PATCHED_FLAG])
+        return () => { };
+    const bodyCap = opts.bodyCap ?? DEFAULT_BODY_CAP;
+    const denylist = opts.denylist ?? DEFAULT_DENYLIST;
+    const emit = (entry) => {
+        try {
+            opts.onEntry(entry);
+        }
+        catch {
+            /* swallow */
+        }
+    };
+    const Patched = function PatchedWebSocket(url, protocols) {
+        const urlStr = typeof url === 'string' ? url : url.toString();
+        const ws = protocols !== undefined
+            ? new OriginalWS(url, protocols)
+            : new OriginalWS(url);
+        if (denylist.some((re) => re.test(urlStr)))
+            return ws;
+        const id = generateId();
+        const protoList = Array.isArray(protocols)
+            ? protocols
+            : typeof protocols === 'string'
+                ? [protocols]
+                : undefined;
+        const openInitiator = captureInitiator();
+        emit({
+            ts: Date.now(),
+            id,
+            phase: 'open',
+            url: urlStr,
+            protocols: protoList,
+            initiator: openInitiator,
+        });
+        ws.addEventListener('message', (ev) => {
+            const { payload, truncated } = serializeFrame(ev.data, bodyCap);
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'recv',
+                url: urlStr,
+                payload,
+                payloadTruncated: truncated || undefined,
+            });
+        });
+        ws.addEventListener('close', (ev) => {
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'close',
+                url: urlStr,
+                code: ev.code,
+                reason: ev.reason || undefined,
+                wasClean: ev.wasClean,
+            });
+        });
+        // Wrap `send` on this instance so we record outgoing payloads + caller.
+        const origSend = ws.send.bind(ws);
+        ws.send = function patchedSend(data) {
+            const initiator = captureInitiator();
+            const { payload, truncated } = serializeFrame(data, bodyCap);
+            emit({
+                ts: Date.now(),
+                id,
+                phase: 'send',
+                url: urlStr,
+                payload,
+                payloadTruncated: truncated || undefined,
+                initiator,
+            });
+            return origSend(data);
+        };
+        return ws;
+    };
+    // Preserve constructor surface so library detection still works.
+    Patched.prototype = OriginalWS.prototype;
+    for (const key of ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED']) {
+        try {
+            Object.defineProperty(Patched, key, {
+                value: OriginalWS[key],
+                writable: false,
+                configurable: true,
+            });
+        }
+        catch {
+            /* readonly already — ignore */
+        }
+    }
+    try {
+        Object.defineProperty(Patched, 'name', { value: 'WebSocket' });
+    }
+    catch {
+        /* ignore */
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Patched[PATCHED_FLAG] = true;
+    window.WebSocket = Patched;
+    return () => {
+        if (window.WebSocket === Patched) {
+            window.WebSocket = OriginalWS;
+        }
+    };
+}
+function generateId() {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    return `ws_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function serializeFrame(data, cap) {
+    if (typeof data === 'string') {
+        if (data.length <= cap) {
+            // Try JSON for structured payloads.
+            const parsed = tryJson(data);
+            return { payload: parsed !== undefined ? parsed : data, truncated: false };
+        }
+        return { payload: data.slice(0, cap), truncated: true };
+    }
+    if (data instanceof ArrayBuffer) {
+        return { payload: `[binary ArrayBuffer ${data.byteLength}B]`, truncated: false };
+    }
+    if (typeof Blob !== 'undefined' && data instanceof Blob) {
+        return { payload: `[binary Blob ${data.size}B]`, truncated: false };
+    }
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return { payload: `[binary ${view.constructor.name} ${view.byteLength}B]`, truncated: false };
+    }
+    return { payload: undefined, truncated: false };
+}
+function tryJson(s) {
+    const trimmed = s.trim();
+    if (!trimmed)
+        return undefined;
+    const first = trimmed[0];
+    if (first !== '{' && first !== '[' && first !== '"')
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/xhrPatch.js

@@ -17,6 +17,7 @@
  *    (XHR has no init-style options bag like fetch)
  *  - Idempotent install + dispose() restores original prototype methods
  */
+import { captureInitiator } from './initiator.js';
 const DEFAULT_BODY_CAP = 256 * 1024;
 const PATCHED_FLAG = '__hfeXhrPatched';
 const META_KEY = Symbol.for('@harness-fe/xhr-meta');
@@ -73,6 +74,7 @@ export function installXhrPatch(opts) {
         }
         meta.startedAt = performance.now();
         meta.startedTs = Date.now();
+        const initiator = captureInitiator();
         // Emit req eagerly with headers; body added on second emit after
         // serialization (mirrors fetchPatch behavior).
         const reqRecord = {
@@ -82,6 +84,7 @@ export function installXhrPatch(opts) {
             method: meta.method,
             url: meta.url,
             requestHeaders: redactHeaders(meta.headers),
+            initiator,
         };
         emit(reqRecord);
         meta.reqEmitted = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/runtime",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Browser-side SDK injected into the dev page. Connects to the MCP server via WebSocket and executes commands.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@zumer/snapdom": "^2.12.0",
     "rrweb": "2.0.0-alpha.4",
-    "@harness-fe/protocol": "3.0.0"
+    "@harness-fe/protocol": "3.1.0"
   },
   "devDependencies": {
     "happy-dom": "^20.9.0",

package/src/capture.ts

@@ -9,30 +9,45 @@ import type {
     ConsoleEntry,
     ErrorEntry,
     NetworkEntry,
+    WsEntry,
+    StorageEntry,
 } from '@harness-fe/protocol';
 import { RingBuffer } from './buffer.js';
 import { installFetchPatch } from './fetchPatch.js';
 import { installXhrPatch } from './xhrPatch.js';
+import { installWsPatch } from './wsPatch.js';
+import { installStoragePatch } from './storagePatch.js';
 
 const CONSOLE_CAP = 500;
 const NETWORK_CAP = 200;
 const ERROR_CAP = 200;
+const WS_CAP = 200;
+const STORAGE_CAP = 200;
 
 export class CaptureStore {
     readonly console = new RingBuffer<ConsoleEntry>(CONSOLE_CAP);
     readonly network = new RingBuffer<NetworkEntry>(NETWORK_CAP);
     readonly errors = new RingBuffer<ErrorEntry>(ERROR_CAP);
+    readonly ws = new RingBuffer<WsEntry>(WS_CAP);
+    readonly storage = new RingBuffer<StorageEntry>(STORAGE_CAP);
 
     private installed = false;
     private fetchDispose?: () => void;
     private xhrDispose?: () => void;
+    private wsDispose?: () => void;
+    private storageDispose?: () => void;
 
-    install(onEvent: (name: string, payload: unknown) => void): void {
+    install(
+        onEvent: (name: string, payload: unknown) => void,
+        opts: { daemonUrl?: string } = {},
+    ): void {
         if (this.installed) return;
         this.installed = true;
         this.installConsole(onEvent);
         this.installFetch(onEvent);
         this.installXhr(onEvent);
+        this.installWs(onEvent, opts.daemonUrl);
+        this.installStorage(onEvent);
         this.installErrors(onEvent);
     }
 
@@ -41,6 +56,10 @@ export class CaptureStore {
         this.fetchDispose = undefined;
         this.xhrDispose?.();
         this.xhrDispose = undefined;
+        this.wsDispose?.();
+        this.wsDispose = undefined;
+        this.storageDispose?.();
+        this.storageDispose = undefined;
         this.installed = false;
     }
 
@@ -79,6 +98,33 @@ export class CaptureStore {
         });
     }
 
+    private installWs(onEvent: (name: string, payload: unknown) => void, daemonUrl?: string): void {
+        // Add the daemon URL itself to the denylist so our own bridge
+        // connection isn't intercepted (otherwise every event we send
+        // would emit a `ws send` that loops back into the outbox).
+        const extra: RegExp[] = [];
+        if (daemonUrl) {
+            const escaped = daemonUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            extra.push(new RegExp(`^${escaped}`));
+        }
+        this.wsDispose = installWsPatch({
+            denylist: extra.length > 0 ? [/\/__hfe\//, /sockjs-node/, ...extra] : undefined,
+            onEntry: (entry) => {
+                this.ws.push(entry);
+                onEvent('ws', entry);
+            },
+        });
+    }
+
+    private installStorage(onEvent: (name: string, payload: unknown) => void): void {
+        this.storageDispose = installStoragePatch({
+            onEntry: (entry) => {
+                this.storage.push(entry);
+                onEvent('storage', entry);
+            },
+        });
+    }
+
     private installErrors(onEvent: (name: string, payload: unknown) => void): void {
         if (typeof window === 'undefined') return;
         window.addEventListener('error', (e: ErrorEvent) => {

package/src/client.ts

@@ -163,7 +163,11 @@ export class RuntimeClient {
 
 
     start(): void {
-        this.ctx.capture.install((name, payload) => this.sendEvent(name, payload));
+        const daemonUrl = this.opts.mcpUrl ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+        this.ctx.capture.install(
+            (name, payload) => this.sendEvent(name, payload),
+            { daemonUrl },
+        );
         this.recorder.start();
         this.connect();
     }

package/src/commands.ts

@@ -305,21 +305,178 @@ export const commandHandlers: Record<string, CommandHandler> = {
     },
 
     [COMMAND.CONSOLE_TAIL]: async (raw, ctx) => {
-        const args = raw as { n: number };
-        return { entries: ctx.capture.console.tail(args.n) };
+        const args = raw as TailArgs & { level?: string };
+        const all = ctx.capture.console.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+            if (args.level && e.level !== args.level) return undefined;
+            return JSON.stringify({ level: e.level, args: e.args });
+        }) };
     },
 
     [COMMAND.NETWORK_TAIL]: async (raw, ctx) => {
-        const args = raw as { n: number };
-        return { entries: ctx.capture.network.tail(args.n) };
+        const args = raw as TailArgs & {
+            urlContains?: string;
+            method?: string;
+            statusCode?: number;
+        };
+        const all = ctx.capture.network.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+            if (args.urlContains && !e.url.includes(args.urlContains)) return undefined;
+            if (args.method && e.method.toUpperCase() !== args.method.toUpperCase()) return undefined;
+            if (args.statusCode !== undefined && e.status !== args.statusCode) return undefined;
+            return JSON.stringify({ url: e.url, method: e.method, requestBody: e.requestBody, responseBody: e.responseBody });
+        }) };
     },
 
     [COMMAND.ERRORS_TAIL]: async (raw, ctx) => {
-        const args = raw as { n: number };
-        return { entries: ctx.capture.errors.tail(args.n) };
+        const args = raw as TailArgs;
+        const all = ctx.capture.errors.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) =>
+            JSON.stringify({ message: e.message, stack: e.stack, source: e.source }),
+        ) };
+    },
+
+    [COMMAND.WS_TAIL]: async (raw, ctx) => {
+        const args = raw as TailArgs & { phase?: string };
+        const all = ctx.capture.ws.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+            if (args.phase && e.phase !== args.phase) return undefined;
+            return JSON.stringify({ url: e.url, payload: e.payload, reason: e.reason });
+        }) };
+    },
+
+    [COMMAND.NETWORK_WAIT_FOR]: async (raw, ctx) => {
+        const args = raw as {
+            urlContains?: string;
+            urlRegex?: string;
+            method?: string;
+            statusCode?: number;
+            timeoutMs?: number;
+        };
+        const timeoutMs = args.timeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        const regex = args.urlRegex ? safeRegex(args.urlRegex) : undefined;
+        // Anchor on the existing buffer head so we only consider new requests
+        // (otherwise an old matching entry would resolve immediately).
+        const baselineLen = ctx.capture.network.size();
+        while (Date.now() < deadline) {
+            const all = ctx.capture.network.tail(500);
+            const newOnes = all.slice(Math.max(0, all.length - (ctx.capture.network.size() - baselineLen)));
+            for (const e of newOnes) {
+                if (args.urlContains && !e.url.includes(args.urlContains)) continue;
+                if (regex && !regex.test(e.url)) continue;
+                if (args.method && e.method.toUpperCase() !== args.method.toUpperCase()) continue;
+                if (args.statusCode !== undefined && e.status !== args.statusCode) continue;
+                return { ok: true, entry: e, after: Date.now() };
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`network.wait_for: no matching request within ${timeoutMs}ms`);
+    },
+
+    [COMMAND.NETWORK_WAIT_FOR_IDLE]: async (raw, ctx) => {
+        const args = raw as { idleMs?: number; timeoutMs?: number };
+        const idleMs = args.idleMs ?? 500;
+        const timeoutMs = args.timeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        let lastSize = ctx.capture.network.size();
+        let stableSince = Date.now();
+        while (Date.now() < deadline) {
+            const currentSize = ctx.capture.network.size();
+            if (currentSize !== lastSize) {
+                lastSize = currentSize;
+                stableSince = Date.now();
+            } else if (Date.now() - stableSince >= idleMs) {
+                return { ok: true, idleFor: Date.now() - stableSince, after: Date.now() };
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`network.wait_for_idle: never quiet for ${idleMs}ms within ${timeoutMs}ms`);
+    },
+
+    [COMMAND.NETWORK_GET]: async (raw, ctx) => {
+        const args = raw as { reqId: string };
+        // Return both req + res entries for this id (one or both may exist).
+        const all = ctx.capture.network.tail(200);
+        const matches = all.filter((e) => e.id === args.reqId);
+        return { entries: matches, found: matches.length > 0 };
+    },
+
+    [COMMAND.WS_GET]: async (raw, ctx) => {
+        const args = raw as { wsId: string };
+        const all = ctx.capture.ws.tail(200);
+        const matches = all.filter((e) => e.id === args.wsId);
+        return { entries: matches, found: matches.length > 0 };
+    },
+
+    [COMMAND.STORAGE_TAIL]: async (raw, ctx) => {
+        const args = raw as TailArgs & {
+            which?: string;
+            op?: string;
+            key?: string;
+        };
+        const all = ctx.capture.storage.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+            if (args.which && e.which !== args.which) return undefined;
+            if (args.op && e.op !== args.op) return undefined;
+            if (args.key && e.key !== args.key) return undefined;
+            return JSON.stringify({ op: e.op, which: e.which, key: e.key, value: e.value });
+        }) };
     },
 };
 
+interface TailArgs {
+    n?: number;
+    filter?: string;
+    match?: 'contains' | 'regex';
+}
+
+/**
+ * Apply caller-supplied filtering to a tail() result. `pickHaystack` returns
+ * the string to match against (or `undefined` to drop the entry due to a
+ * type-specific narrow like `level` / `urlContains`). The shared `filter`
+ * string then runs as substring (default) or regex against the haystack.
+ */
+function safeRegex(source: string): RegExp | undefined {
+    try {
+        return new RegExp(source, 'i');
+    } catch {
+        return undefined;
+    }
+}
+
+function filterTail<T>(
+    items: T[],
+    args: TailArgs,
+    pickHaystack: (item: T) => string | undefined,
+): T[] {
+    const filter = args.filter?.trim();
+    const useRegex = args.match === 'regex';
+    let regex: RegExp | undefined;
+    if (filter && useRegex) {
+        try {
+            regex = new RegExp(filter, 'i');
+        } catch {
+            // Invalid regex: fall back to substring match rather than throwing.
+            regex = undefined;
+        }
+    }
+    const out: T[] = [];
+    for (const item of items) {
+        const haystack = pickHaystack(item);
+        if (haystack === undefined) continue;
+        if (filter) {
+            if (regex) {
+                if (!regex.test(haystack)) continue;
+            } else {
+                if (!haystack.toLowerCase().includes(filter.toLowerCase())) continue;
+            }
+        }
+        out.push(item);
+    }
+    return out;
+}
+
 function truncate(s: string, n: number): string {
     if (s.length <= n) return s;
     return `${s.slice(0, n)}… (truncated, total ${s.length} chars)`;

package/src/commandsFilter.test.ts

@@ -0,0 +1,167 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from 'vitest';
+import { COMMAND, type ConsoleEntry, type NetworkEntry, type WsEntry, type ErrorEntry } from '@harness-fe/protocol';
+import { commandHandlers } from './commands.js';
+import type { CaptureStore } from './capture.js';
+
+/**
+ * Construct a fake CaptureStore wide enough to drive the *_TAIL handlers.
+ * We seed the RingBuffers directly so we don't have to actually patch fetch /
+ * console / WebSocket in this test.
+ */
+function makeCapture(seed: {
+    console?: ConsoleEntry[];
+    network?: NetworkEntry[];
+    errors?: ErrorEntry[];
+    ws?: WsEntry[];
+}): CaptureStore {
+    function ring<T>(items: T[]): { tail: (n: number) => T[] } {
+        return { tail: (n) => items.slice(-n) };
+    }
+    return {
+        console: ring(seed.console ?? []),
+        network: ring(seed.network ?? []),
+        errors: ring(seed.errors ?? []),
+        ws: ring(seed.ws ?? []),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any;
+}
+
+describe('console.tail filtering', () => {
+    const seed: ConsoleEntry[] = [
+        { ts: 1, level: 'log', args: ['boot complete'] },
+        { ts: 2, level: 'warn', args: ['cache miss'] },
+        { ts: 3, level: 'error', args: ['logout failed', { reason: 'token expired' }] },
+        { ts: 4, level: 'log', args: ['heartbeat'] },
+    ];
+
+    it('filter substring (case-insensitive)', async () => {
+        const out = await commandHandlers[COMMAND.CONSOLE_TAIL](
+            { n: 10, filter: 'LOGOUT' },
+            { capture: makeCapture({ console: seed }) },
+        ) as { entries: ConsoleEntry[] };
+        expect(out.entries.map((e) => e.level)).toEqual(['error']);
+    });
+
+    it('filter regex', async () => {
+        const out = await commandHandlers[COMMAND.CONSOLE_TAIL](
+            { n: 10, filter: 'boot|heart', match: 'regex' },
+            { capture: makeCapture({ console: seed }) },
+        ) as { entries: ConsoleEntry[] };
+        expect(out.entries).toHaveLength(2);
+    });
+
+    it('level narrow', async () => {
+        const out = await commandHandlers[COMMAND.CONSOLE_TAIL](
+            { n: 10, level: 'error' },
+            { capture: makeCapture({ console: seed }) },
+        ) as { entries: ConsoleEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].args[0]).toBe('logout failed');
+    });
+
+    it('invalid regex falls back to substring', async () => {
+        const out = await commandHandlers[COMMAND.CONSOLE_TAIL](
+            { n: 10, filter: '[bad', match: 'regex' },
+            { capture: makeCapture({ console: seed }) },
+        ) as { entries: ConsoleEntry[] };
+        // No entry literally contains "[bad" — fallback returns 0 matches.
+        expect(out.entries).toHaveLength(0);
+    });
+});
+
+describe('network.tail filtering', () => {
+    const seed: NetworkEntry[] = [
+        { ts: 1, id: 'r1', phase: 'req', method: 'GET', url: 'https://api.test/users' },
+        { ts: 2, id: 'r1', phase: 'res', method: 'GET', url: 'https://api.test/users', status: 200 },
+        { ts: 3, id: 'r2', phase: 'req', method: 'POST', url: 'https://api.test/logout' },
+        { ts: 4, id: 'r2', phase: 'res', method: 'POST', url: 'https://api.test/logout', status: 401 },
+        { ts: 5, id: 'r3', phase: 'req', method: 'GET', url: 'https://cdn.test/assets/app.js' },
+    ];
+
+    it('urlContains narrow', async () => {
+        const out = await commandHandlers[COMMAND.NETWORK_TAIL](
+            { n: 10, urlContains: 'logout' },
+            { capture: makeCapture({ network: seed }) },
+        ) as { entries: NetworkEntry[] };
+        expect(out.entries.every((e) => e.url.includes('logout'))).toBe(true);
+        expect(out.entries).toHaveLength(2);
+    });
+
+    it('method narrow (case-insensitive)', async () => {
+        const out = await commandHandlers[COMMAND.NETWORK_TAIL](
+            { n: 10, method: 'post' },
+            { capture: makeCapture({ network: seed }) },
+        ) as { entries: NetworkEntry[] };
+        expect(out.entries.every((e) => e.method === 'POST')).toBe(true);
+    });
+
+    it('statusCode narrow (drops req entries without status)', async () => {
+        const out = await commandHandlers[COMMAND.NETWORK_TAIL](
+            { n: 10, statusCode: 401 },
+            { capture: makeCapture({ network: seed }) },
+        ) as { entries: NetworkEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].status).toBe(401);
+    });
+
+    it('filter combined with narrow', async () => {
+        const out = await commandHandlers[COMMAND.NETWORK_TAIL](
+            { n: 10, urlContains: 'api.test', filter: 'logout' },
+            { capture: makeCapture({ network: seed }) },
+        ) as { entries: NetworkEntry[] };
+        expect(out.entries.every((e) => e.url.includes('logout'))).toBe(true);
+    });
+});
+
+describe('ws.tail filtering', () => {
+    const seed: WsEntry[] = [
+        { ts: 1, id: 'w1', phase: 'open', url: 'wss://chat.test/' },
+        { ts: 2, id: 'w1', phase: 'send', url: 'wss://chat.test/', payload: { type: 'ping' } },
+        { ts: 3, id: 'w1', phase: 'recv', url: 'wss://chat.test/', payload: { type: 'kick', reason: 'duplicate-login' } },
+        { ts: 4, id: 'w1', phase: 'close', url: 'wss://chat.test/', code: 4001, reason: 'duplicate-login' },
+    ];
+
+    it('phase narrow', async () => {
+        const out = await commandHandlers[COMMAND.WS_TAIL](
+            { n: 10, phase: 'recv' },
+            { capture: makeCapture({ ws: seed }) },
+        ) as { entries: WsEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].phase).toBe('recv');
+    });
+
+    it('filter against payload', async () => {
+        const out = await commandHandlers[COMMAND.WS_TAIL](
+            { n: 10, filter: 'kick' },
+            { capture: makeCapture({ ws: seed }) },
+        ) as { entries: WsEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].phase).toBe('recv');
+    });
+
+    it('filter against close reason', async () => {
+        const out = await commandHandlers[COMMAND.WS_TAIL](
+            { n: 10, filter: 'duplicate-login', phase: 'close' },
+            { capture: makeCapture({ ws: seed }) },
+        ) as { entries: WsEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].code).toBe(4001);
+    });
+});
+
+describe('errors.tail filtering', () => {
+    const seed: ErrorEntry[] = [
+        { ts: 1, message: 'Cannot read property foo of undefined', stack: 'at A.run', source: 'a.js:1:1' },
+        { ts: 2, message: 'NetworkError', stack: 'at fetchX', source: 'net.js:9:9' },
+    ];
+
+    it('filter by message substring', async () => {
+        const out = await commandHandlers[COMMAND.ERRORS_TAIL](
+            { n: 10, filter: 'network' },
+            { capture: makeCapture({ errors: seed }) },
+        ) as { entries: ErrorEntry[] };
+        expect(out.entries).toHaveLength(1);
+        expect(out.entries[0].message).toBe('NetworkError');
+    });
+});