tracegist-mcp-bridge 0.2.2 → 0.2.4

package/bin/tracegist-mcp-bridge.mjs

@@ -3,12 +3,27 @@
 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";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  isTraceGistPackageFile,
+  normalizeZipBaseName,
+  renderPackagesText,
+  parseMarkdownSections,
+  renderSectionToc,
+  looksLikeVoiceNote,
+  mapConcurrent,
+  toolError,
+  formatExecError,
+  HANDOFF_SUFFIXES,
+} from "./lib.mjs";
 
 const BRIDGE_NAME = "tracegist-mcp-bridge";
 const { version: BRIDGE_VERSION } = JSON.parse(
@@ -25,9 +40,6 @@ function resolveDefaultDirectory() {
 }
 
 const DEFAULT_DOWNLOADS_DIR = resolveDefaultDirectory();
-const PACKAGE_SUFFIX = "-package.zip";
-const HANDOFF_SUFFIXES = ["-coding-agent-handoff.md", "-cursor-handoff.md"];
-const MAX_PREVIEW_CHARS = 12_000;
 const ZIP_CACHE_MAX = 5;
 const execFileAsync = promisify(execFile);
 let whisperDependencyWarnings = [];
@@ -35,6 +47,9 @@ let whisperDependencyWarnings = [];
 /** @type {Map<string, { zip: JSZip, entryNames: string[], mtimeMs: number }>} */
 const zipCache = new Map();
 
+/** @type {Map<string, { enrichedMarkdown: string, mtimeMs: number }>} */
+const transcriptCache = new Map();
+
 async function checkWhisperDependencies() {
   const warnings = [];
 
@@ -70,15 +85,6 @@ async function checkWhisperDependencies() {
   return warnings;
 }
 
-function formatExecError(err) {
-  if (err instanceof Error && err.message) return err.message;
-  return String(err);
-}
-
-function isTraceGistPackageFile(fileName) {
-  return fileName.startsWith("tracegist-") && fileName.endsWith(PACKAGE_SUFFIX);
-}
-
 async function listTraceGistPackages(directory, limit) {
   const entries = await fs.readdir(directory, { withFileTypes: true });
   const zipNames = entries
@@ -144,10 +150,6 @@ async function tryReadManifest(zip) {
   }
 }
 
-function normalizeZipBaseName(entryName) {
-  return path.posix.basename(entryName).toLowerCase();
-}
-
 async function tryReadHandoffMarkdown(zip, entryNames, manifest = null) {
   const manifestNamedHandoff =
     typeof manifest?.handoffMarkdownFilename === "string"
@@ -181,100 +183,8 @@ async function tryReadHandoffMarkdown(zip, entryNames, manifest = null) {
   return { handoffMarkdown, handoffEntryName: selectedEntryName, debugCandidates: [] };
 }
 
-function renderPackagesText(packages, directory) {
-  if (packages.length === 0) {
-    return [
-      `No TraceGist package zips found in ${directory}.`,
-      "Expected naming pattern: tracegist-...-package.zip",
-    ].join("\n");
-  }
-  const lines = [`Found ${packages.length} TraceGist package(s) in ${directory}:`, ""];
-  for (const pkg of packages) {
-    lines.push(
-      `- ${pkg.name}`,
-      `  path: ${pkg.path}`,
-      `  size: ${pkg.sizeBytes} bytes`,
-      `  modified: ${pkg.modifiedAt}`,
-      "",
-    );
-  }
-  return lines.join("\n");
-}
-
-function truncateText(value, maxChars = MAX_PREVIEW_CHARS) {
-  if (value.length <= maxChars) return value;
-  return `${value.slice(0, maxChars)}\n\n... [truncated ${value.length - maxChars} chars]`;
-}
-
-function parseMarkdownSections(markdown) {
-  const sections = [];
-  const lines = markdown.split("\n");
-  let currentName = null;
-  let currentStart = 0;
-
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith("## ")) {
-      if (currentName !== null) {
-        sections.push({
-          name: currentName,
-          content: lines.slice(currentStart, i).join("\n"),
-        });
-      }
-      currentName = lines[i].slice(3).trim();
-      currentStart = i;
-    }
-  }
-
-  if (currentName !== null) {
-    sections.push({
-      name: currentName,
-      content: lines.slice(currentStart).join("\n"),
-    });
-  }
-
-  return sections;
-}
-
-function renderSectionToc(sections, zipPath) {
-  const totalChars = sections.reduce((sum, s) => sum + s.content.length, 0);
-  const lines = [
-    `Handoff document for ${path.basename(zipPath)} — ${sections.length} sections, ${totalChars.toLocaleString()} chars total.`,
-    "",
-    "| # | Section | Size |",
-    "|---|---------|------|",
-  ];
-  for (let i = 0; i < sections.length; i++) {
-    lines.push(
-      `| ${i + 1} | ${sections[i].name} | ${sections[i].content.length.toLocaleString()} chars |`,
-    );
-  }
-  lines.push(
-    "",
-    'Pass `section` with a section name (e.g. "Marker Timeline") to retrieve its full content.',
-  );
-  return lines.join("\n");
-}
-
-function looksLikeVoiceNote(entryName) {
-  const base = path.posix.basename(entryName).toLowerCase();
-  return /voice/.test(base) && /\.(webm|wav|mp3|m4a|ogg|flac)$/i.test(base);
-}
-
 const WHISPER_CONCURRENCY = 2;
 
-async function mapConcurrent(items, fn, concurrency) {
-  const results = new Array(items.length);
-  let i = 0;
-  const worker = async () => {
-    while (i < items.length) {
-      const idx = i++;
-      results[idx] = await fn(items[idx], idx);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
-  return results;
-}
-
 async function transcribeWithLocalWhisper(audioPath, model, language) {
   const args = [
     "-m",
@@ -337,7 +247,9 @@ async function injectTranscriptsIntoMarkdown(markdown, zip, entryNames) {
             transcriptByShortId.set(shortId, "[VOICE NOTE NOT FOUND IN ZIP]");
             return;
           }
-          const outputPath = path.join(tmpRoot, path.basename(entryName));
+          const markerDir = path.join(tmpRoot, shortId);
+          await fs.mkdir(markerDir, { recursive: true });
+          const outputPath = path.join(markerDir, path.basename(entryName));
           const data = await entry.async("nodebuffer");
           await fs.writeFile(outputPath, data);
           try {
@@ -411,27 +323,58 @@ server.registerPrompt(
             "Each package contains screenshots, voice notes, network logs, interaction events, and a",
             "pre-generated handoff markdown file.",
             "",
-            "## Recommended workflow",
+            "## Step 1 — Discover & orient",
             "",
             "1. `list_tracegist_packages` — find available packages (searches TRACEGIST_DIR env var, or ~/Downloads by default).",
-            "2. `get_tracegist_handoff_markdown` — call without a `section` parameter to get a table of contents",
-            '   showing all sections and their sizes. Then request specific sections by name (e.g. `section: "Marker Timeline"`).',
+            "2. `get_tracegist_handoff_markdown` — call **without** a `section` parameter to get a table of contents (TOC)",
+            "   showing all sections, their sizes, and a brief purpose hint for each section.",
+            '   Then request specific sections by name (e.g. `section: "Marker Timeline"`).',
             '   Use `section: "all"` to load the full document at once (can be large for deep exports).',
             "   **Voice note transcripts are injected automatically** into the marker sections — no separate step needed.",
             "   If Whisper is unavailable, a placeholder is injected with setup instructions.",
-            "3. `read_tracegist_package_file` — read text files directly from the ZIP without writing to disk.",
-            "   - **Playwright repro script**: the manifest's `playwrightScriptPath` field gives the entry name.",
-            "     Call `read_tracegist_package_file({ zipPath, entryName: manifest.playwrightScriptPath })`.",
-            "   - **Network bodies**: `network/api-requests.jsonl` has POST/PUT/PATCH bodies + response statuses.",
-            "   - Also useful for the raw manifest JSON or any other text entry.",
-            "4. `extract_tracegist_package_file` — extract a file to disk.",
-            "   Use for: screenshots (PNG) and other binary files, or when a downstream tool needs a real file path.",
+            "",
+            "## Step 2 — Decide: analyze-only vs. reproduce-first",
+            "",
+            "After reading the TOC, choose one of two paths:",
+            "",
+            "### Path A: Analyze and fix (no reproduction needed)",
+            "",
+            "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**.",
+            "5. Diagnose and fix directly in the codebase.",
+            "",
+            "### Path B: Reproduce first, then develop against the reproduction",
+            "",
+            "Best when you need to see the failure live, the bug is intermittent, or you want a test harness to develop against.",
+            "",
+            "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.",
+            "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).",
+            "   - `npx playwright test <script>.spec.ts` — adapt the script as needed, then develop your fix against it.",
+            "6. Once the bug reproduces, switch to Path A sections for root-cause analysis.",
+            "",
+            "## Additional tools",
+            "",
+            "- `read_tracegist_package_file` — read any text file directly from the ZIP without writing to disk.",
+            "  - **Network bodies**: `network/api-requests.jsonl` has POST/PUT/PATCH bodies + response statuses.",
+            "  - Also useful for the raw manifest JSON or any other text entry.",
+            "- `extract_tracegist_package_file` — extract a file to disk.",
+            "  Use for: screenshots (PNG) and other binary files, or when a downstream tool needs a real file path.",
             "",
             "## Key facts",
             "",
-            "- **Overview vs. full handoff**: `get_tracegist_package_overview` returns a TRUNCATED handoff preview",
-            "  (first 12,000 chars — may cut off mid-section). Do NOT treat it as the complete handoff.",
-            "  Always follow up with `get_tracegist_handoff_markdown` (no section → TOC, then load sections by name).",
+            "- **Overview vs. full handoff**: `get_tracegist_package_overview` returns only metadata (manifest + file list).",
+            "  It does NOT include handoff content. Always use `get_tracegist_handoff_markdown`",
+            "  (no section → TOC, then load sections by name) for the actual handoff document.",
             "- Voice notes answer the triage prompts shown to the tester during recording.",
             "  The first marker within 30 s of session start is a session context note (starting state, not a bug).",
             "- Marker timestamps are relative to session start. Each marker has a ±5 s event window",
@@ -442,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"),
         },
       },
@@ -454,113 +416,133 @@ server.registerTool(
   {
     description:
       "Transcribe voice-note files inside a TraceGist package zip using local Python Whisper (no external API).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      model: z.string().optional(),
-      language: z.string().optional(),
+      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."),
     }),
   },
   async ({ zipPath, model = "base", language }) => {
-    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,
-            ),
-          },
-        ],
-      };
-    }
-
-    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 outputPath = path.join(tmpRoot, path.basename(entryName));
-        const data = await entry.async("nodebuffer");
-        await fs.writeFile(outputPath, data);
-        extracted.push({ entryName, outputPath });
+      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,
+        };
       }
 
-      // 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 { 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,
+              ),
+            },
+          ],
+        };
+      }
+
+      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 } : {}),
-    };
+      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);
+    }
   },
 );
 
@@ -569,17 +551,36 @@ server.registerTool(
   {
     description:
       "List TraceGist marker package zip files. Searches TRACEGIST_DIR (env var), falls back to ~/Downloads, or uses the given directory.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      directory: z.string().optional(),
-      limit: z.number().int().min(1).max(200).optional(),
+      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 }) => {
-    const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
-    const packages = await listTraceGistPackages(searchDir, limit);
-    return {
-      content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
-    };
+    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);
+    }
   },
 );
 
@@ -587,35 +588,41 @@ server.registerTool(
   "get_tracegist_package_overview",
   {
     description:
-      "Quick overview of a TraceGist package: manifest, file list, and a TRUNCATED handoff preview (first 12,000 chars only — may cut off mid-section). " +
-      "For the full handoff, call get_tracegist_handoff_markdown (no section param → table of contents, then load sections by name). " +
+      "Quick metadata overview of a TraceGist package: manifest and file list. " +
+      "Does NOT include handoff content — call get_tracegist_handoff_markdown (no section param → table of contents, then load sections by name) for the actual handoff. " +
       "The manifest includes playwrightScriptPath — use read_tracegist_package_file with that path to get the Playwright repro script.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
+      zipPath: z.string().describe("Absolute path to the TraceGist package zip file."),
     }),
   },
   async ({ zipPath }) => {
-    const { zip, entryNames } = await readZipEntries(zipPath);
-    const { manifest, manifestEntryName } = await tryReadManifest(zip);
-    const { handoffMarkdown, handoffEntryName } = await tryReadHandoffMarkdown(
-      zip,
-      entryNames,
-      manifest,
-    );
-
-    const overview = {
-      zipPath,
-      entryCount: entryNames.length,
-      manifestEntryName,
-      handoffEntryName,
-      manifest,
-      handoffPreview: handoffMarkdown ? truncateText(handoffMarkdown, MAX_PREVIEW_CHARS) : null,
-      entries: entryNames,
-    };
+    try {
+      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.",
+      };
 
-    return {
-      content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
-    };
+      return {
+        content: [{ type: "text", text: JSON.stringify(overview, null, 2) }],
+      };
+    } catch (err) {
+      return toolError(err);
+    }
   },
 );
 
@@ -629,92 +636,117 @@ server.registerTool(
       "Without a `section` parameter, returns a table of contents with section names and sizes. " +
       "With a `section` parameter, returns just that section's content. " +
       'Use section name "all" to retrieve the full document.',
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      section: z.string().optional(),
+      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.',
+        ),
     }),
   },
   async ({ zipPath, section }) => {
-    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 enrichedMarkdown = await injectTranscriptsIntoMarkdown(handoffMarkdown, zip, entryNames);
+    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,
+        };
+      }
 
-    // Full document retrieval
-    if (section && section.toLowerCase() === "all") {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
-          },
-        ],
-      };
-    }
+      // 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 });
+      }
 
-    const sections = parseMarkdownSections(enrichedMarkdown);
+      // Full document retrieval
+      if (section && section.toLowerCase() === "all") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `# Source: ${handoffEntryName}\n\n${enrichedMarkdown}`,
+            },
+          ],
+        };
+      }
 
-    // No section requested — return table of contents
-    if (!section) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
-          },
-        ],
-      };
-    }
+      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)}`,
+            },
+          ],
+        };
+      }
 
-    // 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,
-        },
-      ],
-    };
   },
 );
 
@@ -725,24 +757,36 @@ server.registerTool(
       "Read a text file directly from inside a TraceGist package zip and return its content without writing to disk. " +
       "Common uses: `network/api-requests.jsonl` for request/response bodies, or the Playwright repro script " +
       "(its path is in the manifest's `playwrightScriptPath` field, returned by get_tracegist_package_overview).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      entryName: z.string(),
+      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)."),
     }),
   },
   async ({ zipPath, entryName }) => {
-    const { zip } = await readZipEntries(zipPath);
-    const entry = zip.file(entryName);
-    if (!entry) {
+    try {
+      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 }],
-    };
   },
 );
 
@@ -750,40 +794,474 @@ server.registerTool(
   "extract_tracegist_package_file",
   {
     description: "Extract one file from a TraceGist package zip to a local directory.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     inputSchema: z.object({
-      zipPath: z.string(),
-      entryName: z.string(),
-      outputDirectory: z.string().optional(),
+      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."),
     }),
   },
   async ({ zipPath, entryName, outputDirectory }) => {
-    const { zip } = await readZipEntries(zipPath);
-    const entry = zip.file(entryName);
-    if (!entry) {
+    try {
+      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;
+
+/** @type {Array<{seq: number, ts: number, eventType: string, data: object}>} */
+const liveEvents = [];
+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 = [];
+
+function startLiveShadowServer() {
+  let port = LIVE_SHADOW_PORT;
+  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)`);
+          }
+        }
+      });
+    });
+
+    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(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) {
+        liveEvents.shift();
+      }
+      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 || [],
+      });
+      break;
+
+    case "question-dismissed":
+      questionResponses.set(msg.questionId, { dismissed: true });
+      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 "session-end":
+      liveSessionActive = false;
+      console.error(`[${BRIDGE_NAME}] Live shadow: session ended`);
+      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,
+            },
+            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 outDir = path.resolve(outputDirectory || path.dirname(zipPath));
-    const outputPath = path.resolve(outDir, path.basename(entryName));
-    if (!outputPath.startsWith(outDir + path.sep) && outputPath !== outDir) {
+
+    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() });
+
+    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,
     };
+    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) {
+      content.push({
+        type: "text",
+        text: "Voice note is attached. Use the transcribe_tracegist_package_voice_notes tool or listen locally.",
+      });
+    }
+
+    // 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 +1274,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);