tracegist-mcp-bridge 0.2.3 → 0.2.5

package/bin/lib.mjs

@@ -79,9 +79,10 @@ const SECTION_HINTS = {
   "backend log correlation": "Absolute timestamps for server-side log alignment",
   "full session console timeline": "All console output (deep exports only)",
   "full session network timeline": "All network requests (deep exports only)",
-  "full session network timeline (third-party only)": "Third-party network calls (deep exports only)",
+  "full session network timeline (third-party only)":
+    "Third-party network calls (deep exports only)",
   "full session timelines": "Placeholder when deep timelines are omitted",
-  "context": "AI-generated analysis context (when available)",
+  context: "AI-generated analysis context (when available)",
   "tracegist agent-processed context": "LLM-processed summary of the session",
   "tester intent": "What the tester was trying to accomplish",
   "handover tasks for coding agent": "Specific tasks the tester wants the agent to do",

package/bin/tracegist-mcp-bridge.mjs

@@ -3,8 +3,11 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import crypto from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
 import JSZip from "jszip";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -338,10 +341,10 @@ server.registerPrompt(
             "",
             "Best when the bug is clear from logs/screenshots and you can identify the root cause from the trace alone.",
             "",
-            '1. Read **Session Triage** — the tester\'s summary: what was expected, what happened, severity.',
-            '2. Read **Marker Timeline** — timestamped markers with ±5 s event windows (errors, network, interactions).',
-            '3. Read **Notable Anomalies** — pre-flagged JS errors, failed requests, and console warnings.',
-            '4. If needed: **Full Session Console/Network Timelines** (deep exports only), **Session Environment**.',
+            "1. Read **Session Triage** — the tester's summary: what was expected, what happened, severity.",
+            "2. Read **Marker Timeline** — timestamped markers with ±5 s event windows (errors, network, interactions).",
+            "3. Read **Notable Anomalies** — pre-flagged JS errors, failed requests, and console warnings.",
+            "4. If needed: **Full Session Console/Network Timelines** (deep exports only), **Session Environment**.",
             "5. Diagnose and fix directly in the codebase.",
             "",
             "### Path B: Reproduce first, then develop against the reproduction",
@@ -351,8 +354,8 @@ server.registerPrompt(
             "1. `get_tracegist_package_overview` — get the manifest. Note `playwrightScriptPath`.",
             "2. `read_tracegist_package_file({ zipPath, entryName: manifest.playwrightScriptPath })` — read the",
             "   auto-generated Playwright repro script (click/fill steps derived from the interaction log).",
-            '3. Read **Session Environment** — browser, viewport, URL, OS. Match your local setup.',
-            '4. Read **User Interaction Timeline** — the full sequence of user actions to understand the reproduction flow.',
+            "3. Read **Session Environment** — browser, viewport, URL, OS. Match your local setup.",
+            "4. Read **User Interaction Timeline** — the full sequence of user actions to understand the reproduction flow.",
             "5. Extract and run the Playwright script:",
             "   - `extract_tracegist_package_file` to get the script + config to disk.",
             "   - The script needs authentication handled separately (storageState or global setup).",
@@ -382,6 +385,25 @@ server.registerPrompt(
             "  (returned by `get_tracegist_package_overview`). Read it with:",
             "  `read_tracegist_package_file({ zipPath, entryName: manifest.playwrightScriptPath })`.",
             "  Contains click/fill steps derived from the interaction log — use as a starting point for automated reproduction.",
+            "",
+            "## Live Shadowing Mode (Real-Time Collaboration)",
+            "",
+            "If a live session is active, you can collaborate with the tester in real-time:",
+            "",
+            "1. `watch_live_session` — Poll for recent session events (console, network, errors, interactions).",
+            "   Call every 3-5 seconds. Returns `sessionActive: false` when the session ends.",
+            "2. `get_live_screenshot` — Capture the current tab state.",
+            "3. `ask_tester_question` — Ask the tester a short question (max 200 chars).",
+            "   The question appears as a notification in their browser.",
+            "   They respond with a voice marker (Alt+Shift+M) and optional highlight captures (Alt+Shift+S).",
+            "4. `get_tester_response` — Check for the tester's answer (includes voice note, screenshots, highlights).",
+            "",
+            "Tips:",
+            "- Keep questions short and actionable ('Can you click the Save button again?')",
+            "- Wait for the tester to respond before asking another question",
+            "- Use `get_live_screenshot` to see what they're looking at",
+            "- Watch for errors, 5xx responses, and console.error entries in the live event stream",
+            "- Stop polling when `sessionActive` is false",
           ].join("\n"),
         },
       },
@@ -402,115 +424,125 @@ server.registerTool(
     },
     inputSchema: z.object({
       zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
-      model: z.string().optional().describe('Whisper model size (default: "base"). Options: tiny, base, small, medium, large.'),
-      language: z.string().optional().describe("ISO 639-1 language code (e.g. en, de, ja). Omit for auto-detection."),
+      model: z
+        .string()
+        .optional()
+        .describe(
+          'Whisper model size (default: "base"). Options: tiny, base, small, medium, large.',
+        ),
+      language: z
+        .string()
+        .optional()
+        .describe("ISO 639-1 language code (e.g. en, de, ja). Omit for auto-detection."),
     }),
   },
   async ({ zipPath, model = "base", language }) => {
     try {
-    if (whisperDependencyWarnings.length > 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                zipPath,
-                model,
-                language: language || null,
-                transcriptions: [],
-                failures: [],
-                warning:
-                  "Local Whisper dependencies are missing. Fix the dependency warnings and retry transcription.",
-                dependencyWarnings: whisperDependencyWarnings,
-              },
-              null,
-              2,
-            ),
-          },
-        ],
-        isError: true,
-      };
-    }
-
-    const { zip, entryNames } = await readZipEntries(zipPath);
-    const voiceEntries = entryNames.filter((entryName) => looksLikeVoiceNote(entryName));
-    if (voiceEntries.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                zipPath,
-                model,
-                language: language || null,
-                transcriptions: [],
-                warning: "No voice-note files found in package.",
-              },
-              null,
-              2,
-            ),
-          },
-        ],
-      };
-    }
+      if (whisperDependencyWarnings.length > 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  zipPath,
+                  model,
+                  language: language || null,
+                  transcriptions: [],
+                  failures: [],
+                  warning:
+                    "Local Whisper dependencies are missing. Fix the dependency warnings and retry transcription.",
+                  dependencyWarnings: whisperDependencyWarnings,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
 
-    const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "tracegist-whisper-"));
-    const transcriptions = [];
-    const failures = [];
-    try {
-      // Extract all audio files to disk first (fast I/O, safe to parallelize fully)
-      const extracted = [];
-      for (const entryName of voiceEntries) {
-        const entry = zip.file(entryName);
-        if (!entry) {
-          failures.push({ entryName, error: "Entry missing from zip" });
-          continue;
-        }
-        const entryDir = path.join(tmpRoot, String(extracted.length));
-        await fs.mkdir(entryDir, { recursive: true });
-        const outputPath = path.join(entryDir, path.basename(entryName));
-        const data = await entry.async("nodebuffer");
-        await fs.writeFile(outputPath, data);
-        extracted.push({ entryName, outputPath });
+      const { zip, entryNames } = await readZipEntries(zipPath);
+      const voiceEntries = entryNames.filter((entryName) => looksLikeVoiceNote(entryName));
+      if (voiceEntries.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  zipPath,
+                  model,
+                  language: language || null,
+                  transcriptions: [],
+                  warning: "No voice-note files found in package.",
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
       }
 
-      // Transcribe with bounded concurrency (Whisper is CPU/GPU-heavy)
-      await mapConcurrent(
-        extracted,
-        async ({ entryName, outputPath }) => {
-          try {
-            const transcript = await transcribeWithLocalWhisper(outputPath, model, language);
-            transcriptions.push({ entryName, transcript });
-          } catch (err) {
-            failures.push({
-              entryName,
-              error: err instanceof Error ? err.message : String(err),
-            });
+      const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "tracegist-whisper-"));
+      const transcriptions = [];
+      const failures = [];
+      try {
+        // Extract all audio files to disk first (fast I/O, safe to parallelize fully)
+        const extracted = [];
+        for (const entryName of voiceEntries) {
+          const entry = zip.file(entryName);
+          if (!entry) {
+            failures.push({ entryName, error: "Entry missing from zip" });
+            continue;
           }
-        },
-        WHISPER_CONCURRENCY,
-      );
-    } finally {
-      await fs.rm(tmpRoot, { recursive: true, force: true });
-    }
+          const entryDir = path.join(tmpRoot, String(extracted.length));
+          await fs.mkdir(entryDir, { recursive: true });
+          const outputPath = path.join(entryDir, path.basename(entryName));
+          const data = await entry.async("nodebuffer");
+          await fs.writeFile(outputPath, data);
+          extracted.push({ entryName, outputPath });
+        }
 
-    const result = {
-      zipPath,
-      model,
-      language: language || null,
-      voiceFileCount: voiceEntries.length,
-      transcribedCount: transcriptions.length,
-      transcriptions,
-      failures,
-    };
+        // Transcribe with bounded concurrency (Whisper is CPU/GPU-heavy)
+        await mapConcurrent(
+          extracted,
+          async ({ entryName, outputPath }) => {
+            try {
+              const transcript = await transcribeWithLocalWhisper(outputPath, model, language);
+              transcriptions.push({ entryName, transcript });
+            } catch (err) {
+              failures.push({
+                entryName,
+                error: err instanceof Error ? err.message : String(err),
+              });
+            }
+          },
+          WHISPER_CONCURRENCY,
+        );
+      } finally {
+        await fs.rm(tmpRoot, { recursive: true, force: true });
+      }
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-      ...(transcriptions.length === 0 && failures.length > 0 ? { isError: true } : {}),
-    };
-    } catch (err) { return toolError(err); }
+      const result = {
+        zipPath,
+        model,
+        language: language || null,
+        voiceFileCount: voiceEntries.length,
+        transcribedCount: transcriptions.length,
+        transcriptions,
+        failures,
+      };
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        ...(transcriptions.length === 0 && failures.length > 0 ? { isError: true } : {}),
+      };
+    } catch (err) {
+      return toolError(err);
+    }
   },
 );
 
@@ -526,18 +558,29 @@ server.registerTool(
       openWorldHint: false,
     },
     inputSchema: z.object({
-      directory: z.string().optional().describe("Directory to search for packages. Defaults to TRACEGIST_DIR or ~/Downloads."),
-      limit: z.number().int().min(1).max(200).optional().describe("Maximum number of packages to return (default: 20)."),
+      directory: z
+        .string()
+        .optional()
+        .describe("Directory to search for packages. Defaults to TRACEGIST_DIR or ~/Downloads."),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Maximum number of packages to return (default: 20)."),
     }),
   },
   async ({ directory, limit = 20 }) => {
     try {
-    const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
-    const packages = await listTraceGistPackages(searchDir, limit);
-    return {
-      content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
-    };
-    } catch (err) { return toolError(err); }
+      const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
+      const packages = await listTraceGistPackages(searchDir, limit);
+      return {
+        content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
+      };
+    } catch (err) {
+      return toolError(err);
+    }
   },
 );
 
@@ -560,28 +603,26 @@ server.registerTool(
   },
   async ({ zipPath }) => {
     try {
-    const { zip, entryNames } = await readZipEntries(zipPath);
-    const { manifest, manifestEntryName } = await tryReadManifest(zip);
-    const { handoffEntryName } = await tryReadHandoffMarkdown(
-      zip,
-      entryNames,
-      manifest,
-    );
+      const { zip, entryNames } = await readZipEntries(zipPath);
+      const { manifest, manifestEntryName } = await tryReadManifest(zip);
+      const { handoffEntryName } = await tryReadHandoffMarkdown(zip, entryNames, manifest);
 
-    const overview = {
-      zipPath,
-      entryCount: entryNames.length,
-      manifestEntryName,
-      handoffEntryName,
-      manifest,
-      entries: entryNames,
-      hint: "Use get_tracegist_handoff_markdown (no section param) for a table of contents, then load sections by name.",
-    };
+      const overview = {
+        zipPath,
+        entryCount: entryNames.length,
+        manifestEntryName,
+        handoffEntryName,
+        manifest,
+        entries: entryNames,
+        hint: "Use get_tracegist_handoff_markdown (no section param) for a table of contents, then load sections by name.",
+      };
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
-    };
-    } catch (err) { return toolError(err); }
+      return {
+        content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
+      };
+    } catch (err) {
+      return toolError(err);
+    }
   },
 );
 
@@ -603,102 +644,109 @@ server.registerTool(
     },
     inputSchema: z.object({
       zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
-      section: z.string().optional().describe('Section name from the TOC (e.g. "Marker Timeline"), or "all" for the full document. Omit to get table of contents.'),
+      section: z
+        .string()
+        .optional()
+        .describe(
+          'Section name from the TOC (e.g. "Marker Timeline"), or "all" for the full document. Omit to get table of contents.',
+        ),
     }),
   },
   async ({ zipPath, section }) => {
     try {
-    const { zip, entryNames } = await readZipEntries(zipPath);
-    const { manifest } = await tryReadManifest(zip);
-    const { handoffMarkdown, handoffEntryName, debugCandidates } = await tryReadHandoffMarkdown(
-      zip,
-      entryNames,
-      manifest,
-    );
-    if (!handoffMarkdown) {
-      const hintedEntries = entryNames
-        .filter((name) => /handoff|coding-agent/i.test(path.posix.basename(name)))
-        .slice(0, 5);
-      return {
-        content: [
-          {
-            type: "text",
-            text: [
-              `No handoff markdown entry found in ${zipPath}.`,
-              manifest?.handoffMarkdownFilename
-                ? `Manifest handoff filename: ${manifest.handoffMarkdownFilename}`
-                : "Manifest handoff filename: (missing)",
-              `Matching entry candidates: ${hintedEntries.length > 0 ? hintedEntries.join(", ") : "(none)"}`,
-              `Debug candidates: ${debugCandidates.length > 0 ? debugCandidates.join(", ") : "(none)"}`,
-            ].join("\n"),
-          },
-        ],
-        isError: true,
-      };
-    }
+      const { zip, entryNames } = await readZipEntries(zipPath);
+      const { manifest } = await tryReadManifest(zip);
+      const { handoffMarkdown, handoffEntryName, debugCandidates } = await tryReadHandoffMarkdown(
+        zip,
+        entryNames,
+        manifest,
+      );
+      if (!handoffMarkdown) {
+        const hintedEntries = entryNames
+          .filter((name) => /handoff|coding-agent/i.test(path.posix.basename(name)))
+          .slice(0, 5);
+        return {
+          content: [
+            {
+              type: "text",
+              text: [
+                `No handoff markdown entry found in ${zipPath}.`,
+                manifest?.handoffMarkdownFilename
+                  ? `Manifest handoff filename: ${manifest.handoffMarkdownFilename}`
+                  : "Manifest handoff filename: (missing)",
+                `Matching entry candidates: ${hintedEntries.length > 0 ? hintedEntries.join(", ") : "(none)"}`,
+                `Debug candidates: ${debugCandidates.length > 0 ? debugCandidates.join(", ") : "(none)"}`,
+              ].join("\n"),
+            },
+          ],
+          isError: true,
+        };
+      }
 
-    // Cache transcription results to avoid re-running Whisper on repeated calls
-    const cachedZip = zipCache.get(zipPath);
-    const currentMtime = cachedZip?.mtimeMs ?? 0;
-    const cached = transcriptCache.get(zipPath);
-    let enrichedMarkdown;
-    if (cached && cached.mtimeMs === currentMtime) {
-      enrichedMarkdown = cached.enrichedMarkdown;
-    } else {
-      enrichedMarkdown = await injectTranscriptsIntoMarkdown(handoffMarkdown, zip, entryNames);
-      transcriptCache.set(zipPath, { enrichedMarkdown, mtimeMs: currentMtime });
-    }
+      // Cache transcription results to avoid re-running Whisper on repeated calls
+      const cachedZip = zipCache.get(zipPath);
+      const currentMtime = cachedZip?.mtimeMs ?? 0;
+      const cached = transcriptCache.get(zipPath);
+      let enrichedMarkdown;
+      if (cached && cached.mtimeMs === currentMtime) {
+        enrichedMarkdown = cached.enrichedMarkdown;
+      } else {
+        enrichedMarkdown = await injectTranscriptsIntoMarkdown(handoffMarkdown, zip, entryNames);
+        transcriptCache.set(zipPath, { enrichedMarkdown, mtimeMs: currentMtime });
+      }
 
-    // Full document retrieval
-    if (section && section.toLowerCase() === "all") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
-          },
-        ],
-      };
-    }
+      // Full document retrieval
+      if (section && section.toLowerCase() === "all") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
+            },
+          ],
+        };
+      }
 
-    const sections = parseMarkdownSections(enrichedMarkdown);
+      const sections = parseMarkdownSections(enrichedMarkdown);
 
-    // No section requested — return table of contents
-    if (!section) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
-          },
-        ],
-      };
-    }
+      // No section requested — return table of contents
+      if (!section) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
+            },
+          ],
+        };
+      }
 
-    // Section requested — find by case-insensitive match
-    const sectionLower = section.toLowerCase();
-    const match = sections.find((s) => s.name.toLowerCase() === sectionLower);
-    if (!match) {
-      const available = sections.map((s) => s.name).join(", ");
+      // Section requested — find by case-insensitive match
+      const sectionLower = section.toLowerCase();
+      const match = sections.find((s) => s.name.toLowerCase() === sectionLower);
+      if (!match) {
+        const available = sections.map((s) => s.name).join(", ");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Section "${section}" not found. Available sections: ${available}`,
+            },
+          ],
+          isError: true,
+        };
+      }
       return {
         content: [
           {
             type: "text",
-            text: `Section "${section}" not found. Available sections: ${available}`,
+            text: match.content,
           },
         ],
-        isError: true,
       };
+    } catch (err) {
+      return toolError(err);
     }
-    return {
-      content: [
-        {
-          type: "text",
-          text: match.content,
-        },
-      ],
-    };
-    } catch (err) { return toolError(err); }
   },
 );
 
@@ -717,24 +765,28 @@ server.registerTool(
     },
     inputSchema: z.object({
       zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
-      entryName: z.string().describe("Path of the file inside the zip (e.g. network/api-requests.jsonl)."),
+      entryName: z
+        .string()
+        .describe("Path of the file inside the zip (e.g. network/api-requests.jsonl)."),
     }),
   },
   async ({ zipPath, entryName }) => {
     try {
-    const { zip } = await readZipEntries(zipPath);
-    const entry = zip.file(entryName);
-    if (!entry) {
+      const { zip } = await readZipEntries(zipPath);
+      const entry = zip.file(entryName);
+      if (!entry) {
+        return {
+          content: [{ type: "text", text: `Entry "${entryName}" not found in ${zipPath}.` }],
+          isError: true,
+        };
+      }
+      const text = await entry.async("text");
       return {
-        content: [{ type: "text", text: `Entry "${entryName}" not found in ${zipPath}.` }],
-        isError: true,
+        content: [{ type: "text", text }],
       };
+    } catch (err) {
+      return toolError(err);
     }
-    const text = await entry.async("text");
-    return {
-      content: [{ type: "text", text }],
-    };
-    } catch (err) { return toolError(err); }
   },
 );
 
@@ -751,39 +803,627 @@ server.registerTool(
     inputSchema: z.object({
       zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
       entryName: z.string().describe("Path of the file inside the zip to extract."),
-      outputDirectory: z.string().optional().describe("Directory to write the file to. Defaults to the zip file's directory."),
+      outputDirectory: z
+        .string()
+        .optional()
+        .describe("Directory to write the file to. Defaults to the zip file's directory."),
     }),
   },
   async ({ zipPath, entryName, outputDirectory }) => {
     try {
-    const { zip } = await readZipEntries(zipPath);
-    const entry = zip.file(entryName);
-    if (!entry) {
+      const { zip } = await readZipEntries(zipPath);
+      const entry = zip.file(entryName);
+      if (!entry) {
+        return {
+          content: [{ type: "text", text: `Entry "${entryName}" not found in ${zipPath}.` }],
+          isError: true,
+        };
+      }
+      const outDir = path.resolve(outputDirectory || path.dirname(zipPath));
+      const outputPath = path.resolve(outDir, path.basename(entryName));
+      if (!outputPath.startsWith(outDir + path.sep) && outputPath !== outDir) {
+        return {
+          content: [
+            { type: "text", text: `Refusing to write outside output directory: ${outputPath}` },
+          ],
+          isError: true,
+        };
+      }
+      await fs.mkdir(outDir, { recursive: true });
+      const data = await entry.async("nodebuffer");
+      await fs.writeFile(outputPath, data);
       return {
-        content: [{ type: "text", text: `Entry "${entryName}" not found in ${zipPath}.` }],
-        isError: true,
+        content: [{ type: "text", text: `Extracted ${entryName} -> ${outputPath}` }],
       };
+    } catch (err) {
+      return toolError(err);
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Live Shadowing — WebSocket server + state
+// ---------------------------------------------------------------------------
+
+const LIVE_SHADOW_PORT = 19384;
+const LIVE_SHADOW_PORT_RANGE = 5;
+const LIVE_SHADOW_EVENT_BUFFER_SIZE = 2000;
+const PENDING_QUESTIONS_MAX = 50;
+const OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions";
+const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY || "";
+const LIVE_TRANSCRIPTION_MODEL = "openai/gpt-audio-mini";
+
+/** @type {Array<{seq: number, ts: number, eventType: string, data: object}>} */
+const liveEvents = [];
+let liveEventSeq = 0;
+let liveSessionActive = false;
+/** @type {{sessionId: string, url: string, title: string, startedAt: number} | null} */
+let liveSessionMeta = null;
+/** @type {import("ws").WebSocket | null} */
+let activeConnection = null;
+/** @type {Array<{questionId: string, question: string, sentAt: number}>} */
+const pendingQuestions = [];
+/** @type {Map<string, object>} */
+const questionResponses = new Map();
+
+/** @type {Array<{resolve: Function, reject: Function, timeout: ReturnType<typeof setTimeout>}>} */
+const screenshotWaiters = [];
+
+/**
+ * Transcribe a voice data URL using OpenRouter API or local Whisper fallback.
+ * @param {string} voiceBlobDataUrl - data:audio/...;base64,... URL
+ * @returns {Promise<{transcription?: string, error?: string}>}
+ */
+async function transcribeLiveVoice(voiceBlobDataUrl) {
+  // Try OpenRouter API first
+  if (OPENROUTER_API_KEY) {
+    try {
+      const match = voiceBlobDataUrl.match(/^data:([^;]+);base64,(.+)$/);
+      if (!match) return { error: "Invalid voice data URL format" };
+
+      const mimeType = match[1];
+      const base64Data = match[2];
+      const format = mimeType.includes("wav") ? "wav" : mimeType.includes("mp3") ? "mp3" : "webm";
+
+      const response = await fetch(OPENROUTER_API_URL, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${OPENROUTER_API_KEY}`,
+          "Content-Type": "application/json",
+          "HTTP-Referer": "npm:tracegist-mcp-bridge",
+          "X-Title": "TraceGist MCP Bridge",
+        },
+        body: JSON.stringify({
+          model: LIVE_TRANSCRIPTION_MODEL,
+          messages: [
+            {
+              role: "user",
+              content: [
+                {
+                  type: "text",
+                  text: "Transcribe this voice note verbatim. Return only the transcription text, no commentary.",
+                },
+                { type: "input_audio", input_audio: { data: base64Data, format } },
+              ],
+            },
+          ],
+          temperature: 0,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        return { error: `OpenRouter API error (${response.status}): ${errorText}` };
+      }
+
+      const result = await response.json();
+      const text = result.choices?.[0]?.message?.content?.trim();
+      return text ? { transcription: text } : { error: "Empty transcription response" };
+    } catch (err) {
+      return { error: `OpenRouter transcription failed: ${err instanceof Error ? err.message : String(err)}` };
     }
-    const outDir = path.resolve(outputDirectory || path.dirname(zipPath));
-    const outputPath = path.resolve(outDir, path.basename(entryName));
-    if (!outputPath.startsWith(outDir + path.sep) && outputPath !== outDir) {
+  }
+
+  // Fallback to local Whisper
+  if (whisperDependencyWarnings.length === 0) {
+    try {
+      const match = voiceBlobDataUrl.match(/^data:([^;]+);base64,(.+)$/);
+      if (!match) return { error: "Invalid voice data URL format" };
+
+      const buffer = Buffer.from(match[2], "base64");
+      const ext = match[1].includes("wav") ? "wav" : match[1].includes("mp3") ? "mp3" : "webm";
+      const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "tracegist-live-whisper-"));
+      const tmpPath = path.join(tmpDir, `voice.${ext}`);
+      await fs.writeFile(tmpPath, buffer);
+      try {
+        const text = await transcribeWithLocalWhisper(tmpPath, "base", undefined);
+        return { transcription: text };
+      } finally {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+      }
+    } catch (err) {
+      return { error: `Whisper transcription failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+
+  return { error: "No transcription available (set OPENROUTER_API_KEY or install Whisper)" };
+}
+
+/** Push a live event into the ring buffer with auto-incrementing seq. */
+function pushLiveEvent(eventType, data) {
+  liveEventSeq++;
+  liveEvents.push({ seq: liveEventSeq, ts: Date.now(), eventType, data });
+  if (liveEvents.length > LIVE_SHADOW_EVENT_BUFFER_SIZE) {
+    const evictCount = Math.floor(LIVE_SHADOW_EVENT_BUFFER_SIZE * 0.25);
+    liveEvents.splice(0, evictCount);
+  }
+}
+
+function startLiveShadowServer() {
+  let attempts = 0;
+
+  function tryPort(p) {
+    const httpServer = createServer();
+    const wss = new WebSocketServer({ server: httpServer });
+
+    wss.on("connection", (ws) => {
+      // Only allow one connection at a time
+      if (activeConnection) {
+        try {
+          activeConnection.close();
+        } catch {
+          // ignore
+        }
+      }
+      activeConnection = ws;
+      console.error(`[${BRIDGE_NAME}] Live shadow: extension connected`);
+
+      ws.on("message", (raw) => {
+        try {
+          const msg = JSON.parse(String(raw));
+          handleExtensionMessage(msg);
+        } catch (err) {
+          console.error(`[${BRIDGE_NAME}] Live shadow: invalid message:`, err);
+        }
+      });
+
+      ws.on("close", () => {
+        if (activeConnection === ws) {
+          activeConnection = null;
+          if (liveSessionActive) {
+            liveSessionActive = false;
+            console.error(`[${BRIDGE_NAME}] Live shadow: session ended (extension disconnected)`);
+            try {
+              server.sendResourceListChanged();
+            } catch {
+              // Not all transports support notifications
+            }
+          }
+        }
+      });
+    });
+
+    httpServer.on("error", (err) => {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code === "EADDRINUSE") {
+        attempts++;
+        if (attempts < LIVE_SHADOW_PORT_RANGE) {
+          tryPort(p + 1);
+        } else {
+          console.error(
+            `[${BRIDGE_NAME}] Live shadow: all ports ${LIVE_SHADOW_PORT}-${LIVE_SHADOW_PORT + LIVE_SHADOW_PORT_RANGE - 1} in use, live shadowing disabled`,
+          );
+        }
+      }
+    });
+
+    httpServer.listen(p, "127.0.0.1", () => {
+      console.error(
+        `[${BRIDGE_NAME}] Live shadow WebSocket server listening on ws://127.0.0.1:${p}`,
+      );
+    });
+  }
+
+  tryPort(LIVE_SHADOW_PORT);
+}
+
+function handleExtensionMessage(msg) {
+  switch (msg.type) {
+    case "session-start":
+      liveSessionActive = true;
+      liveSessionMeta = {
+        sessionId: msg.sessionId,
+        url: msg.url,
+        title: msg.title,
+        startedAt: Date.now(),
+      };
+      liveEvents.length = 0;
+      pendingQuestions.length = 0;
+      questionResponses.clear();
+      console.error(`[${BRIDGE_NAME}] Live shadow: session started (${msg.sessionId})`);
+      // Notify MCP clients that resources changed
+      try {
+        server.sendResourceListChanged();
+      } catch {
+        // Not all transports support notifications
+      }
+      break;
+
+    case "event":
+      liveEvents.push({
+        seq: msg.seq,
+        ts: msg.ts,
+        eventType: msg.eventType,
+        data: msg.data,
+      });
+      if (liveEvents.length > LIVE_SHADOW_EVENT_BUFFER_SIZE) {
+        // Batch-evict oldest 25% to amortize the O(n) splice cost
+        const evictCount = Math.floor(LIVE_SHADOW_EVENT_BUFFER_SIZE * 0.25);
+        liveEvents.splice(0, evictCount);
+      }
+      break;
+
+    case "question-response": {
+      questionResponses.set(msg.questionId, {
+        questionId: msg.questionId,
+        timestamp: msg.timestamp,
+        voiceBlobDataUrl: msg.voiceBlobDataUrl || null,
+        screenshot: msg.screenshot || null,
+        highlightCaptures: msg.highlightCaptures || [],
+      });
+      const rIdx = pendingQuestions.findIndex((q) => q.questionId === msg.questionId);
+      if (rIdx >= 0) pendingQuestions.splice(rIdx, 1);
+      break;
+    }
+
+    case "question-dismissed": {
+      questionResponses.set(msg.questionId, { dismissed: true });
+      const dIdx = pendingQuestions.findIndex((q) => q.questionId === msg.questionId);
+      if (dIdx >= 0) pendingQuestions.splice(dIdx, 1);
+      break;
+    }
+
+    case "screenshot-response":
+      // Resolve any pending screenshot waiters
+      for (const waiter of screenshotWaiters.splice(0)) {
+        clearTimeout(waiter.timeout);
+        waiter.resolve(msg.screenshot || null);
+      }
+      break;
+
+    case "marker-voice": {
+      const { markerId, voiceBlobDataUrl } = msg;
+      transcribeLiveVoice(voiceBlobDataUrl)
+        .then((result) => {
+          pushLiveEvent("voice-transcription", {
+            markerId,
+            transcription: result.transcription || null,
+            error: result.error || undefined,
+          });
+        })
+        .catch((err) => {
+          console.error(`[${BRIDGE_NAME}] Live voice transcription failed:`, err);
+          pushLiveEvent("voice-transcription", {
+            markerId,
+            transcription: null,
+            error: String(err),
+          });
+        });
+      break;
+    }
+
+    case "session-end":
+      liveSessionActive = false;
+      console.error(`[${BRIDGE_NAME}] Live shadow: session ended`);
+      try {
+        server.sendResourceListChanged();
+      } catch {
+        // Not all transports support notifications
+      }
+      break;
+  }
+}
+
+// Register live shadowing MCP resource
+server.resource(
+  "live-session-status",
+  "live-session://status",
+  { description: "Current live shadowing session status" },
+  async () => ({
+    contents: [
+      {
+        uri: "live-session://status",
+        text: JSON.stringify(
+          {
+            active: liveSessionActive,
+            session: liveSessionMeta,
+            eventCount: liveEvents.length,
+            pendingQuestions: pendingQuestions.length,
+          },
+          null,
+          2,
+        ),
+        mimeType: "application/json",
+      },
+    ],
+  }),
+);
+
+// Tool: watch_live_session
+server.tool(
+  "watch_live_session",
+  "Watch a live TraceGist shadowing session. Returns buffered events since the given sequence number. " +
+    "Poll every 3-5 seconds to watch events in real-time. " +
+    "Returns sessionActive: false when the session ends.",
+  {
+    since_seq: z
+      .number()
+      .optional()
+      .describe("Return events after this sequence number. Omit for all buffered events."),
+  },
+  async ({ since_seq }) => {
+    if (!liveSessionActive && liveEvents.length === 0) {
+      return toolError(
+        "No active live shadowing session. Ensure the TraceGist extension has Live Shadowing enabled and is recording.",
+      );
+    }
+
+    const events =
+      since_seq != null ? liveEvents.filter((e) => e.seq > since_seq) : [...liveEvents];
+
+    const latestSeq = liveEvents.length > 0 ? liveEvents[liveEvents.length - 1].seq : 0;
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              sessionActive: liveSessionActive,
+              session: liveSessionMeta,
+              events,
+              latestSeq,
+              eventCount: events.length,
+              ...(liveSessionActive
+                ? {
+                    availableActions: [
+                      {
+                        tool: "ask_tester_question",
+                        description:
+                          "Ask the tester a short question (max 200 chars). They respond with voice + highlights.",
+                      },
+                      {
+                        tool: "get_live_screenshot",
+                        description:
+                          "Capture a screenshot of the tester's current browser tab.",
+                      },
+                    ],
+                  }
+                : {}),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  },
+);
+
+// Tool: ask_tester_question
+server.tool(
+  "ask_tester_question",
+  "Ask the tester a short, concise question during a live shadowing session. " +
+    "The question appears as a toast notification in their browser. " +
+    "The tester responds with a voice marker (Alt+Shift+M) and optional highlight captures (Alt+Shift+S). " +
+    "Use get_tester_response to check for their answer.",
+  {
+    question: z
+      .string()
+      .max(200)
+      .describe(
+        "Short, concise question for the tester (max 200 chars). " +
+          "Example: 'Can you click the Save button again?' or 'Does the error appear with a different email?'",
+      ),
+  },
+  async ({ question }) => {
+    if (!liveSessionActive || !activeConnection) {
+      return toolError("No active live shadowing session or extension not connected.");
+    }
+
+    const questionId = crypto.randomUUID();
+    try {
+      activeConnection.send(
+        JSON.stringify({
+          type: "agent-question",
+          questionId,
+          question,
+        }),
+      );
+    } catch (err) {
+      return toolError(`Failed to send question to extension: ${err}`);
+    }
+
+    pendingQuestions.push({ questionId, question, sentAt: Date.now() });
+    while (pendingQuestions.length > PENDING_QUESTIONS_MAX) {
+      pendingQuestions.shift();
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `Question sent to tester (ID: ${questionId}).`,
+            "",
+            "The tester sees the question as a notification in their browser.",
+            "They can respond with:",
+            "- Voice marker: Alt/Option + Shift + M (start/stop recording)",
+            "- Highlight captures: Alt/Option + Shift + S (draw on screen)",
+            "",
+            "Use `get_tester_response` with this question ID to check for their answer.",
+          ].join("\n"),
+        },
+      ],
+    };
+  },
+);
+
+// Tool: get_tester_response
+server.tool(
+  "get_tester_response",
+  "Check for the tester's response to a question asked during live shadowing. " +
+    "Returns the tester's screenshot, highlight captures, and voice note availability.",
+  {
+    question_id: z.string().describe("The question ID returned by ask_tester_question."),
+  },
+  async ({ question_id }) => {
+    const response = questionResponses.get(question_id);
+
+    if (!response) {
       return {
         content: [
-          { type: "text", text: `Refusing to write outside output directory: ${outputPath}` },
+          {
+            type: "text",
+            text: "No response yet. The tester may still be recording their answer. Try again in a few seconds.",
+          },
         ],
-        isError: true,
       };
     }
-    await fs.mkdir(outDir, { recursive: true });
-    const data = await entry.async("nodebuffer");
-    await fs.writeFile(outputPath, data);
-    return {
-      content: [{ type: "text", text: `Extracted ${entryName} -> ${outputPath}` }],
+
+    if (response.dismissed) {
+      questionResponses.delete(question_id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: "The tester dismissed this question without responding.",
+          },
+        ],
+      };
+    }
+
+    // Build multimodal content with images inline
+    const content = [];
+
+    const meta = {
+      questionId: question_id,
+      hasVoice: !!response.voiceBlobDataUrl,
+      hasScreenshot: !!response.screenshot,
+      highlightCount: response.highlightCaptures?.length || 0,
     };
-    } catch (err) { return toolError(err); }
+    content.push({
+      type: "text",
+      text: JSON.stringify(meta, null, 2),
+    });
+
+    // Include screenshot as image
+    if (response.screenshot && response.screenshot.startsWith("data:image/")) {
+      const match = response.screenshot.match(/^data:([^;]+);base64,(.+)$/);
+      if (match) {
+        content.push({
+          type: "image",
+          data: match[2],
+          mimeType: match[1],
+        });
+      }
+    }
+
+    // Include highlight captures as images
+    if (response.highlightCaptures) {
+      for (const hl of response.highlightCaptures) {
+        if (hl.screenshot && hl.screenshot.startsWith("data:image/")) {
+          const match = hl.screenshot.match(/^data:([^;]+);base64,(.+)$/);
+          if (match) {
+            content.push({
+              type: "image",
+              data: match[2],
+              mimeType: match[1],
+            });
+          }
+        }
+      }
+    }
+
+    if (response.voiceBlobDataUrl) {
+      const voiceResult = await transcribeLiveVoice(response.voiceBlobDataUrl);
+      if (voiceResult.transcription) {
+        content.push({
+          type: "text",
+          text: `Voice transcription:\n${voiceResult.transcription}`,
+        });
+      } else {
+        content.push({
+          type: "text",
+          text: `Voice note is attached but could not be transcribed${voiceResult.error ? ` (${voiceResult.error})` : ""}. Set OPENROUTER_API_KEY or install local Whisper for transcription.`,
+        });
+      }
+    }
+
+    // Clean up after retrieval
+    questionResponses.delete(question_id);
+
+    return { content };
   },
 );
 
+// Tool: get_live_screenshot
+server.tool(
+  "get_live_screenshot",
+  "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
+  {},
+  async () => {
+    if (!liveSessionActive || !activeConnection) {
+      return toolError("No active live shadowing session or extension not connected.");
+    }
+
+    // Request screenshot from extension and wait for response
+    const screenshotPromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const idx = screenshotWaiters.findIndex((w) => w.resolve === resolve);
+        if (idx >= 0) screenshotWaiters.splice(idx, 1);
+        reject(new Error("Screenshot request timed out (5s)"));
+      }, 5000);
+      screenshotWaiters.push({ resolve, reject, timeout });
+    });
+
+    try {
+      activeConnection.send(JSON.stringify({ type: "request-screenshot" }));
+    } catch (err) {
+      // Clean up waiter
+      screenshotWaiters.splice(0);
+      return toolError(`Failed to request screenshot: ${err}`);
+    }
+
+    try {
+      const screenshot = await screenshotPromise;
+      if (!screenshot) {
+        return toolError("Extension returned empty screenshot");
+      }
+
+      const match = String(screenshot).match(/^data:([^;]+);base64,(.+)$/);
+      if (match) {
+        return {
+          content: [
+            {
+              type: "image",
+              data: match[2],
+              mimeType: match[1],
+            },
+          ],
+        };
+      }
+
+      return toolError("Screenshot data format not recognized");
+    } catch (err) {
+      return toolError(String(err));
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+
 whisperDependencyWarnings = await checkWhisperDependencies();
 console.error(
   `[${BRIDGE_NAME}] Default package directory: ${DEFAULT_DOWNLOADS_DIR}${process.env.TRACEGIST_DIR ? " (from TRACEGIST_DIR)" : ""}`,
@@ -796,5 +1436,8 @@ if (whisperDependencyWarnings.length > 0) {
   console.error(`[${BRIDGE_NAME}] Whisper dependencies check passed.`);
 }
 
+// Start the live shadow WebSocket server
+startLiveShadowServer();
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracegist-mcp-bridge",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "jszip": "^3.10.1",
+    "ws": "^8.18.0",
     "zod": "^4.3.6"
   }
 }