repoburg 1.3.255 → 1.3.256

package/daemon/dist/tabtape/mcp/tools.js

@@ -0,0 +1,1085 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tools = exports.BODY_PAGE = exports.MAX_TEXT = void 0;
+exports.clampLimit = clampLimit;
+exports.parseCursor = parseCursor;
+exports.window = window;
+exports.kindMatcher = kindMatcher;
+exports.levelMatcher = levelMatcher;
+/**
+ * The MCP tools: read-only questions about recorded sessions. Each returns a
+ * text for the model and the same data as structured content. Texts are
+ * capped at MAX_TEXT bytes; long lists continue through cursors.
+ */
+const errors_1 = require("../errors");
+const format_1 = require("../query/format");
+const network_1 = require("../query/network");
+const perf_1 = require("../query/perf");
+const types_1 = require("../query/types");
+const repro_1 = require("../repro/repro");
+const gofmt_1 = require("./gofmt");
+const params_1 = require("./params");
+const recordLink_1 = require("./recordLink");
+/** Caps the text of one tool result (MCP-R3). Bytes, so it is also a cap on characters. */
+exports.MAX_TEXT = 30000;
+const LIST_BODY_CLIP = 2000;
+exports.BODY_PAGE = 20000;
+const STACK_LINES = 6;
+/** How many WebSocket messages get_request returns at once. */
+const FRAME_PAGE = 100;
+const FRAME_CLIP = 2000;
+/** How many store actions get_context_at lists (ST-R15). */
+const STATE_ACTIONS = 10;
+/** Long animation frames from this long on are freezes worth a summary line. */
+const FREEZE_MS = 500;
+/** The tools over one store. */
+class Tools {
+    constructor(st, rd, opts) {
+        this.st = st;
+        this.rd = rd;
+        this.opts = opts;
+    }
+    // ---------- shared helpers ----------
+    /**
+     * Finds a session by id; "latest" (or empty) picks the recording in
+     * progress, else the most recently started one.
+     */
+    resolve(input) {
+        const id = (0, gofmt_1.goTrimSpace)(input);
+        if (id === '' || (0, gofmt_1.goToLower)(id) === 'latest') {
+            const sessions = this.st.list(); // newest first
+            if (sessions.length === 0)
+                throw new Error('there are no recordings yet: start one from the tabtape extension');
+            for (const sess of sessions) {
+                if (this.live(sess))
+                    return sess;
+            }
+            return sessions[0];
+        }
+        try {
+            return this.st.get(id);
+        }
+        catch (err) {
+            if (!(err instanceof errors_1.NotFoundError))
+                throw err;
+            const ids = this.st
+                .list()
+                .slice(0, 5)
+                .map((s) => s.id);
+            if (ids.length === 0)
+                throw new Error(`session ${(0, gofmt_1.goQuote)(id)} not found, and there are no recordings yet`);
+            throw new Error(`session ${(0, gofmt_1.goQuote)(id)} not found. Recent sessions: ${ids.join(', ')} (or use "latest")`);
+        }
+    }
+    /** Mirrors the replay UI: no end yet and a write in the last 30 seconds. */
+    live(sess) {
+        const lastWrite = sess.lastWriteAt ?? 0;
+        return !sess.endedAt && lastWrite > 0 && this.opts.now() - lastWrite < 30000;
+    }
+    link(id, offset) {
+        return (0, format_1.replayLink)(this.opts.baseURL, id, offset);
+    }
+    headers(m) {
+        return this.opts.showSecrets ? m : this.opts.redact.apply(m);
+    }
+    /** A session's title for resource lists, e.g. "Oct 5 07:47 · Acme Shop". */
+    resourceTitle(sess) {
+        const title = sess.title || sess.url || sess.id;
+        return `${(0, gofmt_1.formatStamp)(sess.startedAt, this.opts.timeZone)} · ${title}`;
+    }
+    // ---------- list_sessions ----------
+    async listSessions(input) {
+        const since = (0, params_1.parseSince)(input.since, this.opts.now());
+        const limit = clampLimit(input.limit, 20, 200);
+        const q = (0, gofmt_1.goToLower)((0, gofmt_1.goTrimSpace)(input.query));
+        const user = (0, gofmt_1.goToLower)((0, gofmt_1.goTrimSpace)(input.user));
+        const out = { sessions: null, matched: 0 };
+        const sessions = [];
+        const b = new gofmt_1.TextBuf();
+        for (const sess of this.st.list()) {
+            const haystack = `${sess.title ?? ''} ${sess.url ?? ''} ${sess.lastUrl ?? ''} ${sess.id} ${sess.userId ?? ''}`;
+            if (q !== '' && !(0, gofmt_1.goToLower)(haystack).includes(q))
+                continue;
+            if (user !== '' && !(0, gofmt_1.goToLower)(sess.userId ?? '').includes(user))
+                continue;
+            if (since !== null && sess.startedAt < since)
+                continue;
+            if (input.has_errors && sess.counts.errors === 0 && sess.counts.netErrors === 0)
+                continue;
+            out.matched++;
+            if (sessions.length >= limit)
+                continue;
+            const so = this.sessionOut(sess);
+            const entry = sessionText(so);
+            if (b.len + (0, gofmt_1.byteLen)(entry) > exports.MAX_TEXT - 200)
+                continue;
+            b.write(entry);
+            sessions.push(so);
+        }
+        if (sessions.length > 0)
+            out.sessions = sessions;
+        let head = `${out.matched} recording(s), newest first`;
+        if (sessions.length < out.matched)
+            head += ` (showing ${sessions.length}; narrow with query, since or limit)`;
+        if (out.matched === 0)
+            head = 'No recordings match. Start one from the tabtape extension (⌥⇧R).';
+        return { text: head + ':\n' + b.toString(), out };
+    }
+    sessionOut(sess) {
+        const end = sess.endedAt || sess.lastTs || sess.startedAt || 0;
+        return {
+            id: sess.id,
+            startedAt: (0, gofmt_1.formatRFC3339)(sess.startedAt, this.opts.timeZone),
+            durationMs: Math.max(end - sess.startedAt, 0),
+            title: sess.title || undefined,
+            url: sess.url || undefined,
+            browser: (0, format_1.browserLabel)(sess.userAgent ?? '') || undefined,
+            pages: sess.counts.pages,
+            clicks: sess.counts.clicks,
+            errors: sess.counts.errors,
+            failedRequests: sess.counts.netErrors,
+            trimmed: sess.truncated || undefined,
+            live: this.live(sess) || undefined,
+            source: sess.source || undefined,
+            user: sess.userId || undefined,
+            perf: sess.perf || undefined,
+            replay: this.link(sess.id, 0),
+        };
+    }
+    // ---------- get_session_summary ----------
+    async getSessionSummary(input) {
+        const sess = this.resolve(input.session_id);
+        return this.summary(sess.id, input.cursor);
+    }
+    /** Renders a session's story. It also backs the session resources. */
+    async summary(id, cursor) {
+        const v = await this.rd.view(id);
+        const start = parseCursor(cursor);
+        const so = this.sessionOut(v.session);
+        so.durationMs = Math.max(so.durationMs, v.duration());
+        const out = { session: so, items: null, total: 0, next_cursor: undefined };
+        const b = new gofmt_1.TextBuf();
+        b.write(`# Session ${so.id}\n${(0, gofmt_1.goQuote)(so.title ?? '')} · ${so.url ?? ''}\n`);
+        b.write(`Started ${(0, gofmt_1.rfc3339DateTime)(so.startedAt)} · duration ${(0, format_1.clockShort)(so.durationMs)} · ${so.browser || 'unknown browser'}\n`);
+        const c = v.session.counts;
+        b.write(`${c.pages} pages · ${c.clicks} clicks · ${c.errors} errors · ${c.netErrors} failed requests · ${c.network} network requests · ${c.console} console messages\n`);
+        if (so.user)
+            b.write(`User: ${so.user} (from tabtape.identify)\n`);
+        const notes = dataNotes(v);
+        if (notes !== '')
+            b.write(notes);
+        if (so.live)
+            b.write('Live: the recording is still being written.\n');
+        if (so.trimmed)
+            b.write('Trimmed: the ring buffer deleted the beginning of this recording.\n');
+        if (!v.replayable)
+            b.write('No replayable snapshot is left; links still open the event lists.\n');
+        b.write(`Replay: ${so.replay}\n\n`);
+        const items = [];
+        const finals = v.finalVitals();
+        for (const l of v.lines) {
+            const s = story(l, finals);
+            if (!s)
+                continue;
+            const off = v.offset(l.ts);
+            items.push({ id: l.id, at: (0, format_1.clock)(off), offsetMs: off, kind: s.kind, text: s.text, replay: this.link(id, off) });
+        }
+        out.total = items.length;
+        if (items.length === 0) {
+            b.write('No user actions, errors or failed requests were recorded.\n');
+            return { text: b.toString(), out };
+        }
+        b.write(`Timeline (${items.length} entries; ids work with get_request and get_context_at):\n`);
+        const shown = [];
+        for (let i = start; i < items.length; i++) {
+            const line = itemLine(items[i]);
+            if (b.len + (0, gofmt_1.byteLen)(line) > exports.MAX_TEXT - 300) {
+                out.next_cursor = String(i);
+                b.write(`… ${items.length - i} more entries. Call again with cursor ${(0, gofmt_1.goQuote)(out.next_cursor)}, or narrow down with get_context_at.\n`);
+                break;
+            }
+            b.write(line);
+            shown.push(items[i]);
+        }
+        if (shown.length > 0)
+            out.items = shown;
+        return { text: b.toString(), out };
+    }
+    // ---------- get_network ----------
+    async getNetwork(input) {
+        const sess = this.resolve(input.session_id);
+        const v = await this.rd.view(sess.id);
+        const statusOK = (0, params_1.statusMatcher)(input.status);
+        const [from, to] = window(input.from, input.to);
+        const start = parseCursor(input.cursor);
+        const kindOK = kindMatcher(input.kind);
+        const limit = clampLimit(input.limit, 50, 500);
+        const urlPart = (0, gofmt_1.goToLower)(input.url_contains);
+        const method = (0, gofmt_1.goToLower)(input.method);
+        const matches = [];
+        for (const l of v.lines) {
+            const n = l.net;
+            if (!n)
+                continue;
+            const off = v.offset(l.ts);
+            if (off < from || (to >= 0 && off > to) || !statusOK(n.status, n.error !== '') || !kindOK(n.kind))
+                continue;
+            if (input.method !== '' && (0, gofmt_1.goToLower)(n.method) !== method)
+                continue;
+            if (urlPart !== '' && !(0, gofmt_1.goToLower)(n.url).includes(urlPart))
+                continue;
+            matches.push(l);
+        }
+        const out = { requests: null, matched: matches.length, next_cursor: undefined };
+        const requests = [];
+        const b = new gofmt_1.TextBuf();
+        b.write(`${matches.length} request(s) in session ${sess.id}`);
+        if (start > 0)
+            b.write(`, from #${start + 1}`);
+        b.write(':\n');
+        for (let i = start; i < matches.length; i++) {
+            if (requests.length === limit) {
+                out.next_cursor = String(i);
+                break;
+            }
+            const l = matches[i];
+            const n = l.net;
+            const rs = this.requestSummary(v, l);
+            let entry;
+            if ((0, types_1.isWebSocket)(n)) {
+                entry = `${rs.at}  WS ${outcome(n)}  ${durText(rs.durationMs)}  ${(0, network_1.framesText)(n.frames)}  ${rs.url}  [${rs.id}] ${rs.replay}\n`;
+            }
+            else {
+                entry = `${rs.at}  ${rs.method} ${outcome(n)}  ${durText(rs.durationMs)}  ${sizeText(rs.size ?? 0)}  ${rs.url}  [${rs.id}] ${rs.replay}\n`;
+            }
+            if (input.include_bodies) {
+                let full = null;
+                try {
+                    full = await v.fullNetwork(l);
+                }
+                catch {
+                    full = null;
+                }
+                if (full) {
+                    rs.reqBody = bodyClip(full.reqBody, LIST_BODY_CLIP) || undefined;
+                    rs.resBody = bodyClip(full.resBody, LIST_BODY_CLIP) || undefined;
+                    entry += bodyText('request body', rs.reqBody ?? '', full.reqBodyNote);
+                    entry += bodyText('response body', rs.resBody ?? '', full.resBodyNote);
+                }
+            }
+            if (b.len + (0, gofmt_1.byteLen)(entry) > exports.MAX_TEXT - 300) {
+                out.next_cursor = String(i);
+                break;
+            }
+            b.write(entry);
+            requests.push(rs);
+        }
+        if (requests.length > 0)
+            out.requests = requests;
+        if (out.next_cursor !== undefined) {
+            b.write(`… more requests. Call again with cursor ${(0, gofmt_1.goQuote)(out.next_cursor)}, or narrow down with status, url_contains, kind or from/to.\n`);
+        }
+        if (matches.length === 0)
+            b.write('No requests match.\n');
+        return { text: b.toString(), out };
+    }
+    requestSummary(v, l) {
+        const off = v.offset(l.ts);
+        const n = l.net;
+        return {
+            id: l.id,
+            at: (0, format_1.clock)(off),
+            offsetMs: off,
+            kind: n.kind,
+            method: n.method,
+            url: n.url,
+            status: n.status || undefined,
+            error: n.error || undefined,
+            durationMs: n.duration,
+            size: (0, types_1.sizeOf)(n) || undefined,
+            frames: framesOut(n.frames),
+            reqBody: undefined,
+            resBody: undefined,
+            replay: this.link(v.session.id, off),
+        };
+    }
+    // ---------- get_request ----------
+    async getRequest(input) {
+        const sess = this.resolve(input.session_id);
+        const v = await this.rd.view(sess.id);
+        const l = findRequest(v, (0, gofmt_1.goTrimSpace)(input.request_id));
+        if (!l) {
+            throw new Error(`request ${(0, gofmt_1.goQuote)(input.request_id)} not found in session ${sess.id}; ids come from get_network or get_session_summary`);
+        }
+        const n = await v.fullNetwork(l);
+        const out = {
+            ...this.requestSummary(v, l),
+            statusText: n.statusText || undefined,
+            ttfbMs: n.ttfb,
+            mime: n.mime || undefined,
+            initiator: n.initiator || undefined,
+            reqHeaders: nonEmptyMap(this.headers(n.reqHeaders)),
+            resHeaders: nonEmptyMap(this.headers(n.resHeaders)),
+            reqBodyNote: n.reqBodyNote || undefined,
+            resBodyNote: n.resBodyNote || undefined,
+            reqBodyLength: undefined,
+            resBodyLength: undefined,
+            next_body_offset: undefined,
+            recorded: undefined,
+            protocol: undefined,
+            remoteAddress: undefined,
+            cache: undefined,
+            worker: undefined,
+            timing: undefined,
+            failureReason: undefined,
+            blockedCookies: undefined,
+            blockedSetCookies: undefined,
+            messages: undefined,
+            messagesTotal: undefined,
+            next_frames_offset: undefined,
+        };
+        if (n.source === 'cdp') {
+            out.recorded = (0, types_1.recorded)(n);
+            out.protocol = n.protocol || undefined;
+            out.remoteAddress = n.remoteAddress || undefined;
+            out.cache = n.cache || undefined;
+            out.worker = n.worker ? { type: n.worker.type, url: n.worker.url } : undefined;
+            out.timing = timingOut(n.timing);
+            out.blockedCookies = cookiesOut(n.blockedCookies);
+            out.blockedSetCookies = cookiesOut(n.blockedSetCookies);
+            if (n.corsErrorStatus !== undefined || n.blockedReason !== '')
+                out.failureReason = (0, network_1.failureReason)(n) || undefined;
+        }
+        const offset = Math.max(input.body_offset, 0);
+        const req = page(n.reqBody, offset);
+        const res = page(n.resBody, offset);
+        out.reqBody = req.text || undefined;
+        out.reqBodyLength = req.length || undefined;
+        out.resBody = res.text || undefined;
+        out.resBodyLength = res.length || undefined;
+        if (req.more || res.more)
+            out.next_body_offset = offset + exports.BODY_PAGE;
+        const b = new gofmt_1.TextBuf();
+        b.write(`${n.method} ${n.url}\n`);
+        const parts = [outcome(n)];
+        if (n.statusText !== '' && n.error === '')
+            parts[0] += ' ' + n.statusText;
+        parts.push(n.kind);
+        if (n.duration !== undefined) {
+            let t = (0, format_1.fmtMs)(n.duration);
+            if (n.ttfb !== undefined)
+                t += ' (headers after ' + (0, format_1.fmtMs)(n.ttfb) + ')';
+            parts.push(t);
+        }
+        if ((0, types_1.sizeOf)(n) > 0)
+            parts.push((0, format_1.fmtBytes)((0, types_1.sizeOf)(n)));
+        parts.push(...nonEmpty(n.mime, n.initiator));
+        if (n.pending)
+            parts.push('still pending when the page unloaded or recording stopped');
+        b.write(`${parts.join(' · ')}\nAt ${out.at} · id ${l.id} · ${out.replay}\n`);
+        writeDeep(b, n, out);
+        writeHeaders(b, 'Request headers', out.reqHeaders);
+        writeFullBody(b, 'Request body', n.reqBody, out.reqBody ?? '', out.reqBodyLength ?? 0, offset, n.reqBodyNote, n.reqBodyTruncated);
+        writeHeaders(b, 'Response headers', out.resHeaders);
+        writeFullBody(b, 'Response body', n.resBody, out.resBody ?? '', out.resBodyLength ?? 0, offset, n.resBodyNote, n.resBodyTruncated);
+        if (out.next_body_offset !== undefined)
+            b.write(`\n… the body continues. Call again with body_offset ${out.next_body_offset}.\n`);
+        if ((0, types_1.isWebSocket)(n))
+            await this.writeMessages(b, v, n, Math.max(input.frames_offset, 0), out);
+        return { text: b.toString(), out };
+    }
+    /** Lists one page of a WebSocket connection's messages. */
+    async writeMessages(b, v, n, offset, out) {
+        const frames = v.lines.filter((fl) => fl.ws !== undefined && fl.ws.conn === n.id);
+        out.messagesTotal = frames.length || undefined;
+        if (frames.length === 0) {
+            b.write('\nNo messages were recorded.\n');
+            return;
+        }
+        if (offset >= frames.length) {
+            b.write(`\nNo messages from #${offset + 1}: the connection has ${frames.length}.\n`);
+            return;
+        }
+        let end = Math.min(offset + FRAME_PAGE, frames.length);
+        b.write(`\nMessages ${offset + 1}–${end} of ${frames.length} (↑ sent, ↓ received):\n`);
+        const messages = [];
+        for (let i = offset; i < end; i++) {
+            const fl = frames[i];
+            let f;
+            try {
+                f = await v.fullWS(fl);
+            }
+            catch (err) {
+                if (err instanceof errors_1.GoneError)
+                    continue;
+                throw err;
+            }
+            const off = v.offset(fl.ts);
+            const fo = {
+                id: fl.id,
+                at: (0, format_1.clock)(off),
+                offsetMs: off,
+                dir: f.dir,
+                opcode: f.opcode,
+                size: f.size,
+                data: f.data !== undefined ? (0, format_1.clip)(f.data, FRAME_CLIP) || undefined : undefined,
+                truncated: f.truncated || undefined,
+                dataOmitted: f.dataOmitted || undefined,
+                dropped: f.dropped || undefined,
+                error: f.error || undefined,
+            };
+            const line = frameLine(fo);
+            if (b.len + (0, gofmt_1.byteLen)(line) > exports.MAX_TEXT - 300) {
+                end = i;
+                break;
+            }
+            b.write(line);
+            messages.push(fo);
+        }
+        if (messages.length > 0)
+            out.messages = messages;
+        if (end < frames.length) {
+            out.next_frames_offset = end || undefined;
+            b.write(`… ${frames.length - end} more messages. Call again with frames_offset ${end}.\n`);
+        }
+    }
+    // ---------- get_console ----------
+    async getConsole(input) {
+        const sess = this.resolve(input.session_id);
+        const v = await this.rd.view(sess.id);
+        const [from, to] = window(input.from, input.to);
+        const start = parseCursor(input.cursor);
+        const levelOK = levelMatcher(input.level);
+        const limit = clampLimit(input.limit, 100, 1000);
+        const textPart = (0, gofmt_1.goToLower)(input.text_contains);
+        const matches = [];
+        for (const l of v.lines) {
+            const c = l.con;
+            if (!c || !levelOK(c.level))
+                continue;
+            const off = v.offset(l.ts);
+            if (off < from || (to >= 0 && off > to))
+                continue;
+            if (textPart !== '' && !(0, gofmt_1.goToLower)(c.text).includes(textPart))
+                continue;
+            matches.push(l);
+        }
+        const out = { messages: null, matched: matches.length, next_cursor: undefined };
+        const messages = [];
+        const b = new gofmt_1.TextBuf();
+        b.write(`${matches.length} console message(s) in session ${sess.id}:\n`);
+        for (let i = start; i < matches.length; i++) {
+            if (messages.length === limit) {
+                out.next_cursor = String(i);
+                break;
+            }
+            const l = matches[i];
+            const c = l.con;
+            const off = v.offset(l.ts);
+            const loc = location(c);
+            const item = {
+                id: l.id,
+                at: (0, format_1.clock)(off),
+                offsetMs: off,
+                level: c.level,
+                source: c.source,
+                text: (0, format_1.clip)(c.text, 2000),
+                stack: undefined,
+                location: (loc.startsWith(' at ') ? loc.slice(4) : loc) || undefined,
+                replay: this.link(sess.id, off),
+            };
+            if (c.level === 'error' || c.level === 'warn')
+                item.stack = shortStack(c.stack) || undefined;
+            let entry = `${item.at}  ${(0, gofmt_1.padRight)(c.level, 5)} ${(0, gofmt_1.padRight)(c.source, 18)} ${(0, format_1.oneLine)(item.text, 600)}${loc}  [${item.id}] ${item.replay}\n`;
+            if (item.stack) {
+                for (const line of item.stack.split('\n'))
+                    entry += '      ' + line + '\n';
+            }
+            if (b.len + (0, gofmt_1.byteLen)(entry) > exports.MAX_TEXT - 300) {
+                out.next_cursor = String(i);
+                break;
+            }
+            b.write(entry);
+            messages.push(item);
+        }
+        if (messages.length > 0)
+            out.messages = messages;
+        if (out.next_cursor !== undefined) {
+            b.write(`… more messages. Call again with cursor ${(0, gofmt_1.goQuote)(out.next_cursor)}, or narrow down with level, text_contains or from/to.\n`);
+        }
+        if (matches.length === 0)
+            b.write('No console messages match.\n');
+        return { text: b.toString(), out };
+    }
+    // ---------- get_context_at ----------
+    async getContextAt(input) {
+        const sess = this.resolve(input.session_id);
+        const v = await this.rd.view(sess.id);
+        const ref = (0, gofmt_1.goTrimSpace)(input.at);
+        let at = -1;
+        const anchor = v.find(ref) ?? findRequest(v, ref);
+        if (anchor) {
+            at = v.offset(anchor.ts);
+        }
+        else {
+            try {
+                at = (0, params_1.parseOffset)(input.at);
+            }
+            catch {
+                at = -1;
+            }
+            if (at < 0)
+                throw new Error(`cannot find ${(0, gofmt_1.goQuote)(input.at)}: pass a time like 01:23.4 or an id from another tool`);
+        }
+        const before = (0, params_1.parseSpan)(input.before, 10000);
+        const after = (0, params_1.parseSpan)(input.after, 2000);
+        const out = { at: (0, format_1.clock)(at), offsetMs: at, items: null, stateActions: undefined };
+        const items = [];
+        const b = new gofmt_1.TextBuf();
+        b.write(`Session ${sess.id} around ${out.at} (from ${(0, format_1.clock)(Math.max(at - before, 0))} to ${(0, format_1.clock)(at + after)}):\n`);
+        let marked = false;
+        const finals = v.finalVitals();
+        for (const l of v.lines) {
+            const off = v.offset(l.ts);
+            if (off < at - before || off > at + after)
+                continue;
+            const c = contextLine(l, finals);
+            if (!c)
+                continue;
+            if (!marked && (l === anchor || (anchor === undefined && off > at))) {
+                if (anchor === undefined)
+                    b.write(`${out.at}  ▶ requested moment\n`);
+                marked = true;
+            }
+            const it = { id: l.id, at: (0, format_1.clock)(off), offsetMs: off, kind: c.kind, text: c.text, replay: this.link(sess.id, off) };
+            let line = itemLine(it);
+            if (l === anchor)
+                line = '▶ ' + line;
+            if (b.len + (0, gofmt_1.byteLen)(line) > exports.MAX_TEXT - 300) {
+                b.write('… cut: narrow the window with before/after.\n');
+                break;
+            }
+            b.write(line);
+            items.push(it);
+        }
+        if (!marked && anchor === undefined)
+            b.write(`${out.at}  ▶ requested moment\n`);
+        if (items.length > 0)
+            out.items = items;
+        else
+            b.write('Nothing was recorded in this window apart from screen changes.\n');
+        const actions = await this.stateActions(v, at);
+        if (actions.length > 0) {
+            out.stateActions = actions;
+            b.write(`\nLast ${actions.length} store action(s) up to ${out.at}:\n`);
+            for (const a of actions) {
+                b.write(`${a.at}  ${a.store}  ${a.action}  [${a.id}]\n`);
+                for (const c of a.changes ?? [])
+                    b.write('      ' + c + '\n');
+            }
+        }
+        return { text: b.toString(), out };
+    }
+    /** The last store actions at or before an offset with the paths they changed (ST-R15). */
+    async stateActions(v, at) {
+        let lines = v.lines.filter((l) => l.state !== undefined && l.state.kind === 'action' && v.offset(l.ts) <= at);
+        lines = lines.slice(Math.max(lines.length - STATE_ACTIONS, 0));
+        const out = [];
+        for (const l of lines) {
+            const s = l.state;
+            const off = v.offset(l.ts);
+            let changes;
+            if (s.burst)
+                changes = ['(type only: over 50 actions per second)'];
+            else if (s.full)
+                changes = ['(the whole state was written: the change was too big to list)'];
+            else
+                changes = await changeTexts(v, l);
+            out.push({
+                id: l.id,
+                at: (0, format_1.clock)(off),
+                offsetMs: off,
+                store: s.store,
+                action: s.action,
+                changes: changes.length > 0 ? changes : undefined,
+                replay: this.link(v.session.id, off),
+            });
+        }
+        return out;
+    }
+    // ---------- get_repro_steps ----------
+    async getReproSteps(input) {
+        const sess = this.resolve(input.session_id);
+        const v = await this.rd.view(sess.id);
+        const [from, to] = window(input.from, input.to);
+        const res = await (0, repro_1.generateRepro)(v, {
+            from,
+            to: Math.max(to, 0),
+            lang: input.lang,
+            baseURL: this.opts.baseURL,
+            timeZone: this.opts.timeZone,
+        });
+        return { text: res.markdown, out: { markdown: res.markdown, steps: res.steps, replay: res.link } };
+    }
+    // ---------- get_record_link ----------
+    async getRecordLink(input) {
+        return (0, recordLink_1.getRecordLink)({ baseURL: this.opts.baseURL, recordToken: this.opts.recordToken }, input);
+    }
+}
+exports.Tools = Tools;
+// ---------- texts ----------
+function sessionText(so) {
+    const flags = [`${so.pages} pages, ${so.clicks} clicks, ${so.errors} errors, ${so.failedRequests} failed requests`];
+    if (so.live)
+        flags.push('live');
+    if (so.trimmed)
+        flags.push('trimmed (beginning deleted by the ring buffer)');
+    switch (so.source) {
+        case 'buffer':
+            flags.push('saved from buffer mode');
+            break;
+        case 'automation':
+            flags.push('started by automation (record link or Playwright)');
+            break;
+    }
+    if (so.user)
+        flags.push('user ' + so.user);
+    if (so.perf === 'poor')
+        flags.push('poor Web Vitals');
+    const started = (0, gofmt_1.rfc3339DateTime)(so.startedAt);
+    return `- ${so.id} · ${started} · ${(0, format_1.clockShort)(so.durationMs)} · ${(0, gofmt_1.goQuote)(so.title ?? '')} · ${so.url ?? ''}\n  ${flags.join(' · ')}\n  ${so.replay}\n`;
+}
+/** Mentions deep mode network data and store actions, which other tools return. */
+function dataNotes(v) {
+    let deep = false;
+    let sockets = 0;
+    let actions = 0;
+    const stores = [];
+    for (const l of v.lines) {
+        if (l.net && l.net.source === 'cdp') {
+            deep = true;
+            if ((0, types_1.isWebSocket)(l.net))
+                sockets++;
+        }
+        else if (l.state) {
+            if (l.state.kind === 'action')
+                actions++;
+            if (!stores.includes(l.state.store))
+                stores.push(l.state.store);
+        }
+    }
+    let b = '';
+    if (deep) {
+        b += `Network recorded in deep mode: real headers and cookies, timing split, failure reasons; ${sockets} WebSocket connection(s) (get_network kind=websocket, get_request pages the messages).\n`;
+    }
+    if (stores.length > 0) {
+        b += `State: ${actions} action(s) in store(s) ${stores.join(', ')} (get_context_at lists the last actions before a moment).\n`;
+    }
+    return b;
+}
+function itemLine(it) {
+    return `${it.at}  ${(0, gofmt_1.padRight)(it.kind, 9)} ${it.text}  [${it.id}] ${it.replay}\n`;
+}
+/**
+ * Describes the lines the replay UI shows in its Events tab. finals holds the
+ * final report of each Web Vitals metric (see View.finalVitals).
+ */
+function story(l, finals) {
+    if (l.ev) {
+        const ev = l.ev;
+        switch (ev.name) {
+            case 'page_view': {
+                const { host, path } = (0, format_1.splitURL)(ev.url);
+                return { kind: 'page', text: `Page viewed ${path} — ${nonEmpty(ev.title, host).join(' · ')}` };
+            }
+            case 'click':
+                return { kind: 'click', text: `Clicked ${label(ev.target)} (${selector(ev.target)})` };
+            case 'rage_click':
+                return { kind: 'rage', text: `Rage click ×${ev.count} on ${label(ev.target)} (${selector(ev.target)})` };
+            case 'change': {
+                let value = '(empty)';
+                if (ev.masked)
+                    value = '•••••••• (password, not recorded)';
+                else if (ev.value !== undefined && ev.value !== '')
+                    value = (0, gofmt_1.goQuote)((0, format_1.oneLine)(ev.value, 200));
+                return { kind: 'change', text: `Changed ${field(ev.target)} → ${value}` };
+            }
+            case 'submit':
+                return { kind: 'submit', text: (0, gofmt_1.goTrimSpace)(`Submitted form ${field(ev.target)} ${ev.method} ${ev.action}`) };
+            case 'marker':
+                return { kind: 'marker', text: 'Marker: ' + ev.label };
+            case 'custom': {
+                let text = 'Event ' + ev.event;
+                const props = (0, perf_1.propsText)(ev.props, 200);
+                if (props !== '')
+                    text += ' (' + props + ')';
+                return { kind: 'custom', text };
+            }
+            case 'identify': {
+                let text = 'Identified user ' + ev.userId;
+                const traits = (0, perf_1.propsText)(ev.traits, 200);
+                if (traits !== '')
+                    text += ' (' + traits + ')';
+                return { kind: 'identify', text };
+            }
+        }
+        return null;
+    }
+    if (l.perf)
+        return perfLine(l, finals, 'poor', FREEZE_MS);
+    if (l.con && l.con.level === 'error') {
+        return { kind: 'error', text: consoleLabel(l.con) + ': ' + (0, format_1.oneLine)((0, format_1.firstLine)(l.con.text), 300) + location(l.con) };
+    }
+    if (l.net && (0, types_1.failed)(l.net))
+        return { kind: 'net-error', text: `${l.net.method} ${l.net.url} → ${outcome(l.net)}` };
+    return null;
+}
+/**
+ * Describes every record get_context_at shows: the story plus successful API
+ * requests and all console levels. Assets are left out unless they failed.
+ */
+function contextLine(l, finals) {
+    const s = story(l, finals);
+    if (s)
+        return s;
+    if (l.perf)
+        return perfLine(l, finals, '', 200);
+    if (l.net && !(0, types_1.isAsset)(l.net)) {
+        return { kind: 'request', text: `${l.net.method} ${l.net.url} → ${outcome(l.net)} ${durText(l.net.duration)}` };
+    }
+    if (l.con)
+        return { kind: l.con.level, text: (0, format_1.oneLine)((0, format_1.firstLine)(l.con.text), 300) + location(l.con) };
+    return null;
+}
+/** A final Web Vitals report with the given rating (any when empty) or a long animation frame of at least minFreeze ms. */
+function perfLine(l, finals, rating, minFreeze) {
+    const p = l.perf;
+    if (!p)
+        return null;
+    if (p.kind === 'vital' && finals.has(l) && (rating === '' || p.rating === rating))
+        return { kind: 'vital', text: (0, perf_1.vitalText)(p) };
+    if (p.kind === 'loaf' && p.duration >= minFreeze) {
+        let text = 'Page froze for ' + (0, format_1.fmtMs)(p.duration);
+        const s = (0, perf_1.longestScript)(p);
+        if (s !== '')
+            text += ' (longest script: ' + s + ')';
+        return { kind: 'freeze', text };
+    }
+    return null;
+}
+/** Adds what deep mode recorded about a request. */
+function writeDeep(b, n, out) {
+    if (n.source !== 'cdp')
+        return;
+    const facts = ['Recorded in ' + (0, types_1.recorded)(n), ...nonEmpty(n.protocol, n.remoteAddress)];
+    if (n.cache !== '')
+        facts.push('from the ' + n.cache + ' cache');
+    else if (n.fromServiceWorker)
+        facts.push((0, gofmt_1.goTrimSpace)('answered by a service worker ' + n.swSource));
+    b.write(facts.join(' · ') + '\n');
+    if (out.failureReason)
+        b.write(`Why it failed: ${out.failureReason}\n`);
+    const t = (0, network_1.timingText)(n.timing);
+    if (t !== '')
+        b.write(`Timing: ${t}\n`);
+    if (n.worker)
+        b.write(`Requested by a ${n.worker.type.split('_').join(' ')}: ${n.worker.url}\n`);
+    for (const c of n.blockedCookies ?? [])
+        b.write(`Cookie not sent: ${c.name} — ${(0, network_1.cookieReasons)(c.reasons)}\n`);
+    for (const c of n.blockedSetCookies ?? [])
+        b.write(`Set-Cookie rejected: ${c.name} — ${(0, network_1.cookieReasons)(c.reasons)}\n`);
+    if ((0, types_1.isWebSocket)(n)) {
+        const closed = n.closedAt > 0 ? 'closed after ' + durText(n.duration) : 'still open when the recording stopped';
+        b.write(`WebSocket ${closed} · ${(0, network_1.framesText)(n.frames)}\n`);
+    }
+}
+function frameLine(f) {
+    let b = '';
+    if (f.dropped)
+        b += `  … ${f.dropped} message(s) not recorded (over 200 per second)\n`;
+    const arrow = f.dir === 'send' ? '↑' : '↓';
+    let what;
+    if (f.error)
+        what = 'error: ' + f.error;
+    else if (f.dataOmitted)
+        what = '(data not recorded: over 1 MB per second)';
+    else if (f.opcode === 2)
+        what = 'binary';
+    else if (f.opcode === 8)
+        what = 'close';
+    else if (f.opcode === 9)
+        what = 'ping';
+    else if (f.opcode === 10)
+        what = 'pong';
+    else {
+        what = (0, format_1.oneLine)(f.data ?? '', FRAME_CLIP);
+        if (f.truncated)
+            what += ' … (cut at 64 KB by the recorder)';
+    }
+    b += `  ${f.at} ${arrow} ${sizeText(f.size)}  ${what}  [${f.id}]\n`;
+    return b;
+}
+/** A request by line id, else by the recorder's own request id. */
+function findRequest(v, id) {
+    const l = v.find(id);
+    if (l && l.net)
+        return l;
+    return v.lines.find((x) => x.net !== undefined && x.net.id === id);
+}
+/** An action's changes as "path = value" lines. */
+async function changeTexts(v, l) {
+    const most = 8;
+    let changes;
+    try {
+        changes = (await v.fullState(l)).changes ?? [];
+    }
+    catch {
+        return l.state.paths.slice(); // deleted meanwhile: paths only
+    }
+    const out = [];
+    for (let i = 0; i < changes.length; i++) {
+        const c = changes[i];
+        if (i === most) {
+            out.push(`… ${changes.length - most} more changed paths`);
+            break;
+        }
+        const path = c.path || '(whole state)';
+        if (c.deleted) {
+            out.push(path + ' deleted');
+            continue;
+        }
+        // The store keeps records as compact JSON, so this is the recorded text.
+        const value = c.value === undefined ? '' : JSON.stringify(c.value);
+        out.push(path + ' = ' + (0, format_1.clip)(value, 120));
+    }
+    if (out.length === 0)
+        out.push('(no state change)');
+    return out;
+}
+// ---------- helpers ----------
+function clampLimit(n, def, most) {
+    return n <= 0 ? def : Math.min(n, most);
+}
+function parseCursor(c) {
+    if (c === '')
+        return 0;
+    const n = (0, params_1.atoi)(c);
+    if (n === null || n < 0)
+        throw new Error(`invalid cursor ${(0, gofmt_1.goQuote)(c)}: pass next_cursor from the previous result`);
+    return n;
+}
+/** Parses from/to; a missing from is 0, a missing to is -1 (the end). */
+function window(fromS, toS) {
+    const from = (0, params_1.parseOffset)(fromS);
+    const to = (0, params_1.parseOffset)(toS);
+    return [Math.max(from, 0), to];
+}
+function kindMatcher(kind) {
+    const k = (0, gofmt_1.goToLower)((0, gofmt_1.goTrimSpace)(kind));
+    switch (k) {
+        case '':
+            return () => true;
+        case 'api':
+            return (x) => x === 'fetch' || x === 'xhr' || x === 'beacon';
+        case 'document':
+        case 'navigation':
+        case 'doc':
+            return (x) => x === 'navigation';
+        case 'resource':
+        case 'asset':
+        case 'assets':
+            return (x) => x === 'resource';
+        case 'fetch':
+        case 'xhr':
+        case 'beacon':
+        case 'websocket':
+            return (x) => x === k;
+        case 'ws':
+        case 'websockets':
+            return (x) => x === 'websocket';
+    }
+    throw new Error(`unknown kind ${(0, gofmt_1.goQuote)(kind)}; use fetch, xhr, beacon, api, document, resource or websocket`);
+}
+function levelMatcher(level) {
+    const l = (0, gofmt_1.goToLower)((0, gofmt_1.goTrimSpace)(level));
+    switch (l) {
+        case '':
+            return () => true;
+        case 'warn+':
+        case 'warning+':
+        case 'warnings':
+            return (x) => x === 'warn' || x === 'error';
+        case 'warning':
+            return (x) => x === 'warn';
+        case 'error':
+        case 'warn':
+        case 'info':
+        case 'log':
+        case 'debug':
+        case 'trace':
+            return (x) => x === l;
+    }
+    throw new Error(`unknown level ${(0, gofmt_1.goQuote)(level)}; use error, warn, warn+, info, log, debug or trace`);
+}
+function outcome(n) {
+    if (n.error !== '' || n.corsErrorStatus !== undefined || n.blockedReason !== '')
+        return 'failed (' + (0, network_1.failureReason)(n) + ')';
+    if (n.pending && (0, types_1.isWebSocket)(n))
+        return 'open';
+    if (n.pending)
+        return 'pending';
+    if (n.status > 0)
+        return String(n.status);
+    if (n.kind === 'beacon')
+        return 'sent';
+    return '—';
+}
+function durText(d) {
+    return d === undefined ? '—' : (0, format_1.fmtMs)(d);
+}
+function sizeText(n) {
+    return n <= 0 ? '—' : (0, format_1.fmtBytes)(n);
+}
+function bodyClip(body, n) {
+    return body === undefined ? '' : (0, format_1.clip)(body, n);
+}
+function bodyText(name, body, note) {
+    if (body !== '')
+        return `    ${name}: ${body.split('\n').join('\n      ')}\n`;
+    if (note !== '')
+        return `    ${name}: (${note})\n`;
+    return '';
+}
+/** One page of a body, counted in code points (Go's runes). */
+function page(body, offset) {
+    if (body === undefined)
+        return { text: '', length: 0, more: false };
+    const length = (0, gofmt_1.runeCount)(body);
+    if (offset >= length)
+        return { text: '', length, more: false };
+    const end = Math.min(offset + exports.BODY_PAGE, length);
+    return { text: runeSlice(body, offset, end), length, more: end < length };
+}
+/** s from rune start to rune end. */
+function runeSlice(s, start, end) {
+    let i = 0;
+    let r = 0;
+    let from = -1;
+    while (i < s.length) {
+        if (r === start)
+            from = i;
+        if (r === end)
+            break;
+        const c = s.charCodeAt(i);
+        const d = s.charCodeAt(i + 1);
+        i += c >= 0xd800 && c <= 0xdbff && d >= 0xdc00 && d <= 0xdfff ? 2 : 1;
+        r++;
+    }
+    if (from < 0)
+        from = i;
+    return s.slice(from, i);
+}
+function writeHeaders(b, title, h) {
+    if (!h)
+        return;
+    const keys = Object.keys(h).sort();
+    if (keys.length === 0)
+        return;
+    b.write(`\n${title}:\n`);
+    for (const k of keys)
+        b.write(`  ${k}: ${h[k]}\n`);
+}
+function writeFullBody(b, title, body, pageText, length, offset, note, truncated) {
+    if (body === undefined) {
+        if (note !== '')
+            b.write(`\n${title}: (${note})\n`);
+        return;
+    }
+    if (length === 0) {
+        b.write(`\n${title}: (empty)\n`);
+        return;
+    }
+    const extra = truncated ? ', cut by the recorder at 1 MB' : '';
+    const n = (0, gofmt_1.runeCount)(pageText);
+    if (offset > 0 || n < length)
+        b.write(`\n${title} (characters ${offset}–${offset + n} of ${length}${extra}):\n${pageText}\n`);
+    else
+        b.write(`\n${title} (${length} characters${extra}):\n${pageText}\n`);
+}
+function shortStack(stack) {
+    if (stack === '')
+        return '';
+    let lines = (0, gofmt_1.goTrimSpace)(stack).split('\n');
+    if (lines.length > STACK_LINES)
+        lines = [...lines.slice(0, STACK_LINES), `… ${lines.length - STACK_LINES} more frames`];
+    return lines.map((l) => (0, format_1.clip)((0, gofmt_1.goTrimSpace)(l), 300)).join('\n');
+}
+function label(t) {
+    const text = (0, format_1.targetText)(t);
+    if (text !== '')
+        return (0, gofmt_1.goQuote)((0, format_1.oneLine)(text, 100));
+    return '<' + (0, format_1.targetTag)(t) + '>';
+}
+function field(t) {
+    const name = (0, format_1.fieldName)(t);
+    if (name !== '')
+        return (0, gofmt_1.goQuote)(name);
+    return '<' + (0, format_1.targetTag)(t) + '>';
+}
+function selector(t) {
+    return !t || t.selector === '' ? 'no selector' : t.selector;
+}
+function consoleLabel(c) {
+    switch (c.source) {
+        case 'uncaught':
+            return 'Uncaught error';
+        case 'unhandledrejection':
+            return 'Unhandled rejection';
+        case 'resource':
+            return 'Resource failed to load';
+    }
+    return 'console.error';
+}
+function location(c) {
+    if (c.url === '')
+        return '';
+    const { path } = (0, format_1.splitURL)(c.url);
+    return c.line > 0 ? ` at ${path}:${c.line}` : ' at ' + path;
+}
+function nonEmpty(...ss) {
+    return ss.filter((s) => s !== '');
+}
+/** A map for JSON output: keys sorted like Go's encoder, nothing when empty (omitempty). */
+function nonEmptyMap(m) {
+    if (!m)
+        return undefined;
+    const keys = Object.keys(m).sort();
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const k of keys)
+        out[k] = m[k];
+    return out;
+}
+function framesOut(f) {
+    if (!f)
+        return undefined;
+    return {
+        sent: f.sent,
+        received: f.received,
+        sentBytes: f.sentBytes,
+        receivedBytes: f.receivedBytes,
+        dropped: f.dropped || undefined,
+        dataOmitted: f.dataOmitted || undefined,
+    };
+}
+function timingOut(t) {
+    if (!t)
+        return undefined;
+    return { blocked: t.blocked, dns: t.dns, connect: t.connect, ssl: t.ssl, send: t.send, wait: t.wait, receive: t.receive };
+}
+function cookiesOut(list) {
+    if (!list || list.length === 0)
+        return undefined;
+    return list.map((c) => ({ name: c.name, reasons: c.reasons, domain: c.domain || undefined, path: c.path || undefined }));
+}