@peekdev/mcp 0.1.0-alpha.1

package/dist/mcp/action-schema.d.ts

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+/** Click on a selector. Optionally pick nth match + which button. */
+export declare const ClickActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+    selector: z.ZodString;
+    nth: z.ZodOptional<z.ZodNumber>;
+    button: z.ZodDefault<z.ZodEnum<["left", "middle", "right"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    button: "left" | "middle" | "right";
+    nth?: number | undefined;
+}, {
+    type: "click";
+    selector: string;
+    nth?: number | undefined;
+    button?: "left" | "middle" | "right" | undefined;
+}>;
+export type ClickAction = z.infer<typeof ClickActionSchema>;
+/** Type into an input. `delay` is per-character in ms. */
+export declare const TypeActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"type">;
+    selector: z.ZodString;
+    text: z.ZodString;
+    delay: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "type";
+    selector: string;
+    text: string;
+    delay: number;
+}, {
+    type: "type";
+    selector: string;
+    text: string;
+    delay?: number | undefined;
+}>;
+export type TypeAction = z.infer<typeof TypeActionSchema>;
+/** Top-frame navigation to a URL. */
+export declare const NavigateActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"navigate">;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "navigate";
+    url: string;
+}, {
+    type: "navigate";
+    url: string;
+}>;
+export type NavigateAction = z.infer<typeof NavigateActionSchema>;
+/** History.back / forward / location.reload — no DOM target. */
+export declare const BackActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"back">;
+}, "strip", z.ZodTypeAny, {
+    type: "back";
+}, {
+    type: "back";
+}>;
+export type BackAction = z.infer<typeof BackActionSchema>;
+export declare const ForwardActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"forward">;
+}, "strip", z.ZodTypeAny, {
+    type: "forward";
+}, {
+    type: "forward";
+}>;
+export type ForwardAction = z.infer<typeof ForwardActionSchema>;
+export declare const ReloadActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"reload">;
+}, "strip", z.ZodTypeAny, {
+    type: "reload";
+}, {
+    type: "reload";
+}>;
+export type ReloadAction = z.infer<typeof ReloadActionSchema>;
+/** Scroll: either to absolute (x,y) or scrollIntoView on the selected element. */
+export declare const ScrollActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+    selector: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "scroll";
+    selector?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+}, {
+    type: "scroll";
+    selector?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+}>;
+export type ScrollAction = z.infer<typeof ScrollActionSchema>;
+/** chrome.tabs.captureVisibleTab — non-mutating, but still a Level-3+ tool. */
+export declare const ScreenshotActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "screenshot";
+    selector?: string | undefined;
+}, {
+    type: "screenshot";
+    selector?: string | undefined;
+}>;
+export type ScreenshotAction = z.infer<typeof ScreenshotActionSchema>;
+/** Wait for a selector to appear or timeoutMs to elapse, whichever first. */
+export declare const WaitForActionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"waitFor">;
+    selector: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "waitFor";
+    timeoutMs: number;
+    selector?: string | undefined;
+}, {
+    type: "waitFor";
+    selector?: string | undefined;
+    timeoutMs?: number | undefined;
+}>;
+export type WaitForAction = z.infer<typeof WaitForActionSchema>;
+/** The full Action discriminated union (P2 PRD §E.4). */
+export declare const ActionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+    selector: z.ZodString;
+    nth: z.ZodOptional<z.ZodNumber>;
+    button: z.ZodDefault<z.ZodEnum<["left", "middle", "right"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    button: "left" | "middle" | "right";
+    nth?: number | undefined;
+}, {
+    type: "click";
+    selector: string;
+    nth?: number | undefined;
+    button?: "left" | "middle" | "right" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"type">;
+    selector: z.ZodString;
+    text: z.ZodString;
+    delay: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "type";
+    selector: string;
+    text: string;
+    delay: number;
+}, {
+    type: "type";
+    selector: string;
+    text: string;
+    delay?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"navigate">;
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "navigate";
+    url: string;
+}, {
+    type: "navigate";
+    url: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"back">;
+}, "strip", z.ZodTypeAny, {
+    type: "back";
+}, {
+    type: "back";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"forward">;
+}, "strip", z.ZodTypeAny, {
+    type: "forward";
+}, {
+    type: "forward";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"reload">;
+}, "strip", z.ZodTypeAny, {
+    type: "reload";
+}, {
+    type: "reload";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+    selector: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "scroll";
+    selector?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+}, {
+    type: "scroll";
+    selector?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "screenshot";
+    selector?: string | undefined;
+}, {
+    type: "screenshot";
+    selector?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"waitFor">;
+    selector: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "waitFor";
+    timeoutMs: number;
+    selector?: string | undefined;
+}, {
+    type: "waitFor";
+    selector?: string | undefined;
+    timeoutMs?: number | undefined;
+}>]>;
+export type Action = z.infer<typeof ActionSchema>;
+/**
+ * Mask the action's sensitive fields for audit-log persistence. `type`
+ * `text` (TypeAction) and `url` query strings can carry passwords / tokens.
+ * We don't have access to the masking primitives via z's own pipeline, so
+ * this is a small explicit helper. Lossy by design.
+ */
+export declare function redactActionForAudit(action: Action): Action;
+//# sourceMappingURL=action-schema.d.ts.map

package/dist/mcp/action-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.d.ts","sourceRoot":"","sources":["../../src/mcp/action-schema.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qEAAqE;AACrE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,qCAAqC;AACrC,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,gEAAgE;AAChE,eAAO,MAAM,gBAAgB;;;;;;EAAwC,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;EAA2C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;EAA0C,CAAC;AAC1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;EAK7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB;;;;;;;;;EAGjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,yDAAyD;AACzD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAUvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqB3D"}

package/dist/mcp/action-schema.js

@@ -0,0 +1,97 @@
+// Action zod schemas (P2 PRD §E.4) used by the two Level-3+ MCP write tools
+// (Task 3.24): `execute_action` validates `Action`, and `request_authorization`
+// accepts the same shape so the side panel banner can describe what it's about
+// to do.
+//
+// Discriminated union on `type` — the SDK auto-converts zod to JSON Schema for
+// MCP tool listings, and clients send back a tagged object the host routes to
+// the MAIN-world dispatcher.
+//
+// Keep this in sync with the dispatcher in
+// `packages/peek-extension/src/permissions/dispatcher.ts`. New `type`s land
+// here first (the source of truth for tool inputSchema), then the dispatcher
+// grows a matching case.
+import { z } from 'zod';
+/** Click on a selector. Optionally pick nth match + which button. */
+export const ClickActionSchema = z.object({
+    type: z.literal('click'),
+    selector: z.string().min(1),
+    nth: z.number().int().min(0).optional(),
+    button: z.enum(['left', 'middle', 'right']).default('left'),
+});
+/** Type into an input. `delay` is per-character in ms. */
+export const TypeActionSchema = z.object({
+    type: z.literal('type'),
+    selector: z.string().min(1),
+    text: z.string(),
+    delay: z.number().int().min(0).default(40),
+});
+/** Top-frame navigation to a URL. */
+export const NavigateActionSchema = z.object({
+    type: z.literal('navigate'),
+    url: z.string().url(),
+});
+/** History.back / forward / location.reload — no DOM target. */
+export const BackActionSchema = z.object({ type: z.literal('back') });
+export const ForwardActionSchema = z.object({ type: z.literal('forward') });
+export const ReloadActionSchema = z.object({ type: z.literal('reload') });
+/** Scroll: either to absolute (x,y) or scrollIntoView on the selected element. */
+export const ScrollActionSchema = z.object({
+    type: z.literal('scroll'),
+    selector: z.string().optional(),
+    x: z.number().int().optional(),
+    y: z.number().int().optional(),
+});
+/** chrome.tabs.captureVisibleTab — non-mutating, but still a Level-3+ tool. */
+export const ScreenshotActionSchema = z.object({
+    type: z.literal('screenshot'),
+    selector: z.string().optional(),
+});
+/** Wait for a selector to appear or timeoutMs to elapse, whichever first. */
+export const WaitForActionSchema = z.object({
+    type: z.literal('waitFor'),
+    selector: z.string().optional(),
+    timeoutMs: z.number().int().min(0).default(5000),
+});
+/** The full Action discriminated union (P2 PRD §E.4). */
+export const ActionSchema = z.discriminatedUnion('type', [
+    ClickActionSchema,
+    TypeActionSchema,
+    NavigateActionSchema,
+    BackActionSchema,
+    ForwardActionSchema,
+    ReloadActionSchema,
+    ScrollActionSchema,
+    ScreenshotActionSchema,
+    WaitForActionSchema,
+]);
+/**
+ * Mask the action's sensitive fields for audit-log persistence. `type`
+ * `text` (TypeAction) and `url` query strings can carry passwords / tokens.
+ * We don't have access to the masking primitives via z's own pipeline, so
+ * this is a small explicit helper. Lossy by design.
+ */
+export function redactActionForAudit(action) {
+    switch (action.type) {
+        case 'type':
+            // Replace the typed text with a token marker so the audit log records
+            // that a TypeAction happened on selector X without preserving the value.
+            return { ...action, text: '<<REDACTED>>' };
+        case 'navigate': {
+            // Strip query-string values (params keep their names, see mask.ts).
+            try {
+                const u = new URL(action.url);
+                for (const key of [...u.searchParams.keys()]) {
+                    u.searchParams.set(key, '<<REDACTED>>');
+                }
+                return { ...action, url: u.href };
+            }
+            catch {
+                return action;
+            }
+        }
+        default:
+            return action;
+    }
+}
+//# sourceMappingURL=action-schema.js.map

package/dist/mcp/action-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.js","sourceRoot":"","sources":["../../src/mcp/action-schema.ts"],"names":[],"mappings":"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"}

package/dist/mcp/event-blobs.d.ts

@@ -0,0 +1,32 @@
+import { type eventWithTime } from '@cubenest/rrweb-core';
+/**
+ * A blob exists on disk but couldn't be decoded — a corrupt/truncated gzip
+ * frame or a payload that doesn't deserialize to an event array. Distinct from
+ * "no blob" (which is a normal empty result): a present-but-broken blob is a
+ * real, attributable failure the tool surfaces clearly rather than silently
+ * treating as zero events.
+ */
+export declare class SessionEventsError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Absolute base directory for the gzipped per-session event blobs. */
+export declare function rrwebEventsDir(): string;
+/**
+ * Resolve a `sessions.events_blob_path` value to an absolute path. The column
+ * stores a path relative to {@link rrwebEventsDir}; an absolute value (older
+ * rows / tests) is honored as-is.
+ */
+export declare function resolveBlobPath(blobPath: string, baseDir?: string): string;
+/**
+ * Read + gunzip + JSON-parse a session's event blob into the rrweb event array.
+ * Returns an empty array when the session has no blob path recorded or the
+ * blob file is missing (e.g. an active session before its first flush, or a
+ * blob pruned by retention) — callers degrade to "no events" rather than throw.
+ *
+ * @param blobPath the `sessions.events_blob_path` value (relative or absolute)
+ * @param baseDir  override the ~/.peek/rrweb-events base (tests)
+ */
+export declare function loadSessionEvents(blobPath: string | null | undefined, baseDir?: string): eventWithTime[];
+//# sourceMappingURL=event-blobs.d.ts.map

package/dist/mcp/event-blobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-blobs.d.ts","sourceRoot":"","sources":["../../src/mcp/event-blobs.ts"],"names":[],"mappings":"AAUA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGtE;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,CAE5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,OAAO,GAAE,MAAyB,GACjC,aAAa,EAAE,CAoBjB"}

package/dist/mcp/event-blobs.js

@@ -0,0 +1,65 @@
+// Locate + load + decompress a session's rrweb event blob (ADR-0007). The
+// native host persists each session's captured `eventWithTime[]` gzipped under
+// ~/.peek/rrweb-events/, referenced by `sessions.events_blob_path` (a path
+// relative to that directory). The event-level MCP tools
+// (get_user_action_before_error, get_dom_snapshot, query_dom_history,
+// generate_playwright_repro) read the blob through here and walk the decoded
+// stream — the console/network tools read the structured SQL tables directly.
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { decompress } from '@cubenest/rrweb-core';
+import { peekHomeDir } from '../db/open.js';
+/**
+ * A blob exists on disk but couldn't be decoded — a corrupt/truncated gzip
+ * frame or a payload that doesn't deserialize to an event array. Distinct from
+ * "no blob" (which is a normal empty result): a present-but-broken blob is a
+ * real, attributable failure the tool surfaces clearly rather than silently
+ * treating as zero events.
+ */
+export class SessionEventsError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SessionEventsError';
+    }
+}
+/** Absolute base directory for the gzipped per-session event blobs. */
+export function rrwebEventsDir() {
+    return join(peekHomeDir(), 'rrweb-events');
+}
+/**
+ * Resolve a `sessions.events_blob_path` value to an absolute path. The column
+ * stores a path relative to {@link rrwebEventsDir}; an absolute value (older
+ * rows / tests) is honored as-is.
+ */
+export function resolveBlobPath(blobPath, baseDir = rrwebEventsDir()) {
+    return isAbsolute(blobPath) ? blobPath : join(baseDir, blobPath);
+}
+/**
+ * Read + gunzip + JSON-parse a session's event blob into the rrweb event array.
+ * Returns an empty array when the session has no blob path recorded or the
+ * blob file is missing (e.g. an active session before its first flush, or a
+ * blob pruned by retention) — callers degrade to "no events" rather than throw.
+ *
+ * @param blobPath the `sessions.events_blob_path` value (relative or absolute)
+ * @param baseDir  override the ~/.peek/rrweb-events base (tests)
+ */
+export function loadSessionEvents(blobPath, baseDir = rrwebEventsDir()) {
+    if (blobPath === null || blobPath === undefined || blobPath.length === 0) {
+        return [];
+    }
+    const abs = resolveBlobPath(blobPath, baseDir);
+    if (!existsSync(abs)) {
+        return [];
+    }
+    const bytes = readFileSync(abs);
+    try {
+        // readFileSync returns a Node Buffer; decompress wants a Uint8Array view.
+        // decompress throws (fflate gzip error / non-array payload) on a corrupt or
+        // truncated blob — translate that into a clear, attributable error.
+        return decompress(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+    }
+    catch (err) {
+        throw new SessionEventsError(`Failed to decode the event blob at '${blobPath}' (corrupt or truncated recording).`, { cause: err });
+    }
+}
+//# sourceMappingURL=event-blobs.js.map

package/dist/mcp/event-blobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-blobs.js","sourceRoot":"","sources":["../../src/mcp/event-blobs.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,2EAA2E;AAC3E,yDAAyD;AACzD,sEAAsE;AACtE,6EAA6E;AAC7E,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAsB,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,UAAkB,cAAc,EAAE;IAClF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAmC,EACnC,UAAkB,cAAc,EAAE;IAElC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,0EAA0E;QAC1E,4EAA4E;QAC5E,oEAAoE;QACpE,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAC1B,uCAAuC,QAAQ,qCAAqC,EACpF,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/mcp/event-walker.d.ts

@@ -0,0 +1,86 @@
+import { type eventWithTime, type serializedNodeWithId } from './rrweb-types.js';
+/** A single extracted user action with the data a repro / explanation needs. */
+export interface UserAction {
+    /** 'click' | 'input' | 'navigate' | 'submit' (a click on a submit control). */
+    readonly type: 'click' | 'input' | 'navigate';
+    /** Epoch-millis of the action (the event's `timestamp`). */
+    readonly ts: number;
+    /** Derived CSS selector for the target node, when resolvable. */
+    readonly selector?: string;
+    /** For input actions: the (already-masked-by-capture) value typed. */
+    readonly value?: string;
+    /** For navigations: the destination URL (Meta event href). */
+    readonly url?: string;
+    /** A short human description, e.g. `click button.submit`. */
+    readonly summary: string;
+}
+/**
+ * Walk the stream and pull out user actions (clicks, input commits, page
+ * navigations) in chronological order. The selector for a click/input is
+ * derived from whichever FullSnapshot is in effect at that point (rebuilt as
+ * new FullSnapshots arrive), with added nodes folded into the index so
+ * interactions on dynamically-inserted elements still resolve.
+ *
+ * Mouse *moves*, scrolls, and non-Click interactions are intentionally dropped
+ * — they're noise for repro/explanation and blow the token budget.
+ */
+export declare function extractUserActions(events: eventWithTime[]): UserAction[];
+/** The user actions strictly before `errorTs`, most-recent-last, capped to `window`. */
+export declare function userActionsBeforeError(events: eventWithTime[], errorTs: number, window?: number): UserAction[];
+/**
+ * Reconstruct the DOM at timestamp `ts` and render it to an HTML-ish string.
+ *
+ * v1 scope (deliberately bounded — see the task's "don't rabbit-hole" note):
+ * start from the most recent FullSnapshot at or before `ts`, then replay
+ * IncrementalSnapshot **mutations** (node adds/removes, attribute changes, text
+ * changes) up to and including `ts`. We do NOT run rrweb's Replayer/jsdom; we
+ * mutate the serialized tree directly and serialize it back. This faithfully
+ * reflects structural/attribute/text state at T — which is what the read tools
+ * need — while skipping canvas/media/stylesheet replay (not needed for DOM
+ * inspection and out of budget). The offset from the base snapshot is reported
+ * so a caller knows how much was applied.
+ *
+ * Returns `undefined` if there is no FullSnapshot at or before `ts`.
+ */
+export interface DomSnapshot {
+    /** Epoch-millis of the FullSnapshot the reconstruction started from. */
+    readonly baseSnapshotTs: number;
+    /** Number of mutation events applied on top of the base snapshot. */
+    readonly mutationsApplied: number;
+    /** The serialized (and mutated) document/element subtree. */
+    readonly root: serializedNodeWithId;
+    /** The rendered HTML-ish string (optionally scoped to a selector subtree). */
+    readonly html: string;
+}
+export declare function reconstructDomAt(events: eventWithTime[], ts: number, selector?: string): DomSnapshot | undefined;
+/**
+ * Render a serialized node tree to an HTML-ish string (lightweight, not
+ * spec-perfect). Stops descending past {@link MAX_DOM_DEPTH} — emitting a
+ * truncation marker instead of recursing — so an adversarial deeply-nested
+ * recording can't overflow the stack (this code ingests untrusted blobs).
+ */
+export declare function serializeNode(node: serializedNodeWithId, depth?: number): string;
+/** A single change in a node's history (query_dom_history). */
+export interface DomChange {
+    readonly ts: number;
+    readonly op: 'attribute' | 'text' | 'added' | 'removed';
+    /** For attribute changes: the attribute name. */
+    readonly attribute?: string;
+    /** The new value (attribute value / text content); null = removed. */
+    readonly value?: string | null;
+}
+/**
+ * Timeline of attribute and/or text changes for the node a `selector` resolves
+ * to in the base FullSnapshot. `op` filters to one dimension; default returns
+ * both. Bounded by `limit` for the token budget.
+ *
+ * v1 resolves the selector against the base FullSnapshot's tree (the common
+ * case — querying a stable element). A selector that only matches a
+ * dynamically-added node is not resolved here; that's a documented v1 limit.
+ */
+export interface QueryDomHistoryOptions {
+    readonly op?: 'attributeChanges' | 'innerText';
+    readonly limit?: number;
+}
+export declare function queryDomHistory(events: eventWithTime[], selector: string, options?: QueryDomHistoryOptions): DomChange[];
+//# sourceMappingURL=event-walker.d.ts.map

package/dist/mcp/event-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-walker.d.ts","sourceRoot":"","sources":["../../src/mcp/event-walker.ts"],"names":[],"mappings":"AAoBA,OAAO,EAOL,KAAK,aAAa,EAKlB,KAAK,oBAAoB,EAE1B,MAAM,kBAAkB,CAAC;AAS1B,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAuBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,CAgExE;AAkBD,wFAAwF;AACxF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,MAAM,SAAK,GACV,UAAU,EAAE,CAGd;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EAAE,EACvB,EAAE,EAAE,MAAM,EACV,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,SAAS,CAkDzB;AAkGD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,SAAI,GAAG,MAAM,CAoC3E;AAiCD,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACxD,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,SAAS,EAAE,CAmDb"}