tracegist-mcp-bridge 0.2.8 → 0.2.12

package/README.md

@@ -43,6 +43,10 @@ Set `TRACEGIST_DIR` to change where the bridge looks for packages (defaults to `
 - `read_tracegist_package_file` — read any text file from inside the ZIP without writing to disk (e.g. `network/api-requests.jsonl`, the Playwright repro script)
 - `extract_tracegist_package_file` — write a binary or text file from the ZIP to a local directory
 - `transcribe_tracegist_package_voice_notes` — transcribe voice notes using local Python Whisper
+- `watch_live_session` — poll real-time session events while recording is active
+- `get_live_screenshot` — request and retrieve a screenshot of the current tab
+- `ask_tester_question` — send a question to the tester (shown as a browser toast, max 200 chars)
+- `get_tester_response` — retrieve the tester's voice + screenshot answer
 
 ## Package contents
 

package/bin/lib.mjs

@@ -11,14 +11,17 @@ export function normalizeZipBaseName(entryName) {
   return path.posix.basename(entryName).toLowerCase();
 }
 
-export function renderPackagesText(packages, directory) {
+export function renderPackagesText(packages, directory, totalCount = null, hasMore = false, offset = 0) {
   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}:`, ""];
+  const countLabel = totalCount != null
+    ? `Showing ${packages.length} of ${totalCount} TraceGist package(s) in ${directory}:`
+    : `Found ${packages.length} TraceGist package(s) in ${directory}:`;
+  const lines = [countLabel, ""];
   for (const pkg of packages) {
     lines.push(
       `- ${pkg.name}`,
@@ -28,6 +31,16 @@ export function renderPackagesText(packages, directory) {
       "",
     );
   }
+  if (hasMore) {
+    lines.push(
+      `More packages available. Use offset: ${offset + packages.length} to see the next page.`,
+      "",
+    );
+  }
+  lines.push(
+    "Each package includes a ready-to-run Playwright repro script.",
+    "Call get_tracegist_handoff_markdown (no section param) on a package to see the TOC with repro script paths.",
+  );
   return lines.join("\n");
 }
 
@@ -74,7 +87,8 @@ const SECTION_HINTS = {
   "user interaction timeline": "Full click/fill/navigation sequence — key for reproduction",
   "session context": "Page URL, title, session metadata",
   "session environment": "Browser, viewport, OS — match for reproduction",
-  "package files": "Paths to Playwright script, manifest, network bodies",
+  "package files":
+    "ACTION: Read the Python repro script path here — use read_tracegist_package_file before writing any automation",
   "marker-to-file mapping": "Which screenshots/voice files belong to each marker",
   "backend log correlation": "Absolute timestamps for server-side log alignment",
   "full session console timeline": "All console output (deep exports only)",
@@ -89,20 +103,54 @@ const SECTION_HINTS = {
   "marker visual evidence": "Screenshot references for each marker",
   "environment at marker time": "Environment snapshot at a specific marker",
   "marker timeline logs (context window)": "Logs within the ±5 s marker window",
+  "webapp testing reproduction":
+    "ACTION: Ready-to-run Python repro script path + key selectors — read before writing any automation",
+  "tester intent summary": "Classified intent: specifications, issues found, observations",
+  "iterative context": "Previous session reference, verification checklist for build-test cycle",
+  "tier 0: quick summary": "Session overview, intent, reproduction command (~200 tokens)",
+  "tier 1: findings": "Marker timeline with structured findings (~500 tokens)",
+  "tier 2: full context": "Interaction timeline, network/console context, environment",
+  "tier 3: deep diagnostics": "Full session timelines (deep profile only)",
 };
 
 function getSectionHint(sectionName) {
   return SECTION_HINTS[sectionName.toLowerCase()] || "Additional section";
 }
 
-export function renderSectionToc(sections, zipPath) {
+export function renderSectionToc(sections, zipPath, manifest = null) {
   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.`,
     "",
+  ];
+
+  // Prominent callout BEFORE the table — shown before any section is read
+  const pythonScript = manifest?.pythonPlaywrightScriptPath;
+  const tsScript = manifest?.playwrightScriptPath;
+  if (pythonScript || tsScript) {
+    lines.push(
+      "**Playwright repro script is ready — read it before writing any automation code:**",
+    );
+    if (pythonScript) {
+      lines.push(
+        `- Python (webapp-testing skill): \`read_tracegist_package_file(zipPath, "${pythonScript}")\``,
+      );
+    }
+    if (tsScript) {
+      lines.push(
+        `- TypeScript (Playwright Test): \`read_tracegist_package_file(zipPath, "${tsScript}")\``,
+      );
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "**Reading guide:** For analysis, start with Session Triage → Marker Timeline → Notable Anomalies.",
+    "For reproduction, start with the Playwright repro script above → Session Environment → User Interaction Timeline.",
+    "",
     "| # | Section | Size | Purpose |",
     "|---|---------|------|---------|",
-  ];
+  );
   for (let i = 0; i < sections.length; i++) {
     const hint = getSectionHint(sections[i].name);
     lines.push(
@@ -110,9 +158,6 @@ export function renderSectionToc(sections, zipPath) {
     );
   }
   lines.push(
-    "",
-    "**Reading guide:** For analysis, start with Session Triage → Marker Timeline → Notable Anomalies.",
-    "For reproduction, start with Session Environment → User Interaction Timeline → Package Files (Playwright script path).",
     "",
     'Pass `section` with a section name (e.g. "Marker Timeline") to retrieve its full content.',
   );

package/bin/tracegist-mcp-bridge.mjs

@@ -85,7 +85,7 @@ async function checkWhisperDependencies() {
   return warnings;
 }
 
-async function listTraceGistPackages(directory, limit) {
+async function listTraceGistPackages(directory, limit, offset = 0) {
   const entries = await fs.readdir(directory, { withFileTypes: true });
   const zipNames = entries
     .filter((entry) => entry.isFile() && isTraceGistPackageFile(entry.name))
@@ -105,7 +105,9 @@ async function listTraceGistPackages(directory, limit) {
   );
 
   packages.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
-  return packages.slice(0, limit);
+  const totalCount = packages.length;
+  const sliced = packages.slice(offset, offset + limit);
+  return { packages: sliced, totalCount, hasMore: offset + limit < totalCount };
 }
 
 async function readZipEntries(zipPath) {
@@ -569,14 +571,26 @@ server.registerTool(
         .max(200)
         .optional()
         .describe("Maximum number of packages to return (default: 20)."),
+      offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Number of packages to skip for pagination (default: 0)."),
     }),
   },
-  async ({ directory, limit = 20 }) => {
+  async ({ directory, limit = 20, offset = 0 }) => {
     try {
       const searchDir = directory || DEFAULT_DOWNLOADS_DIR;
-      const packages = await listTraceGistPackages(searchDir, limit);
+      const { packages, totalCount, hasMore } = await listTraceGistPackages(
+        searchDir,
+        limit,
+        offset,
+      );
       return {
-        content: [{ type: "text", text: renderPackagesText(packages, searchDir) }],
+        content: [
+          { type: "text", text: renderPackagesText(packages, searchDir, totalCount, hasMore, offset) },
+        ],
       };
     } catch (err) {
       return toolError(err);
@@ -715,7 +729,7 @@ server.registerTool(
           content: [
             {
               type: "text",
-              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath)}`,
+              text: `# Source: ${handoffEntryName}\n\n${renderSectionToc(sections, zipPath, manifest)}`,
             },
           ],
         };
@@ -928,7 +942,9 @@ async function transcribeLiveVoice(voiceBlobDataUrl) {
       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)}` };
+      return {
+        error: `OpenRouter transcription failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
     }
   }
 
@@ -950,7 +966,9 @@ async function transcribeLiveVoice(voiceBlobDataUrl) {
         await fs.rm(tmpDir, { recursive: true, force: true });
       }
     } catch (err) {
-      return { error: `Whisper transcription failed: ${err instanceof Error ? err.message : String(err)}` };
+      return {
+        error: `Whisper transcription failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
     }
   }
 
@@ -1233,24 +1251,33 @@ server.resource(
 );
 
 // Tool: watch_live_session
-server.tool(
+server.registerTool(
   "watch_live_session",
-  "Watch a live TraceGist shadowing session in real-time. Returns buffered events since the given sequence number.\n\n" +
-    "IMPORTANT POLLING BEHAVIOR:\n" +
-    "- You MUST keep calling this tool every 2-4 seconds in a loop until sessionActive becomes false.\n" +
-    "- Do NOT stop polling just because there are no new events — the tester is still active.\n" +
-    "- When you see 'voice-transcription' events, the tester recorded a voice marker — read the transcription and react to it.\n" +
-    "- When you see 'question-response-received' events, use get_tester_response to retrieve the full answer with images.\n" +
-    "- When you see 'question-response-transcribed' events, the tester's voice response has been transcribed — read it for context.\n" +
-    "- Marker events with hasPendingVoice=true will have their voiceTranscription field populated once transcription completes.\n" +
-    "- The tester may set voice markers at any time to communicate with you — keep watching for them.\n" +
-    "- If you need clarification, use ask_tester_question to show a toast notification to the tester.\n" +
-    "- Only stop polling when sessionActive is false (the recording ended).",
   {
-    since_seq: z
-      .number()
-      .optional()
-      .describe("Return events after this sequence number. Omit for all buffered events."),
+    description:
+      "Watch a live TraceGist shadowing session in real-time. Returns buffered events since the given sequence number.\n\n" +
+      "IMPORTANT POLLING BEHAVIOR:\n" +
+      "- You MUST keep calling this tool every 2-4 seconds in a loop until sessionActive becomes false.\n" +
+      "- Do NOT stop polling just because there are no new events — the tester is still active.\n" +
+      "- When you see 'voice-transcription' events, the tester recorded a voice marker — read the transcription and react to it.\n" +
+      "- When you see 'question-response-received' events, use get_tester_response to retrieve the full answer with images.\n" +
+      "- When you see 'question-response-transcribed' events, the tester's voice response has been transcribed — read it for context.\n" +
+      "- Marker events with hasPendingVoice=true will have their voiceTranscription field populated once transcription completes.\n" +
+      "- The tester may set voice markers at any time to communicate with you — keep watching for them.\n" +
+      "- If you need clarification, use ask_tester_question to show a toast notification to the tester.\n" +
+      "- Only stop polling when sessionActive is false (the recording ended).",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({
+      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) {
@@ -1273,7 +1300,11 @@ server.tool(
       }
     }
     const enrichedEvents = events.map((e) => {
-      if (e.eventType === "marker" && e.data?.markerId && transcriptionsByMarkerId.has(e.data.markerId)) {
+      if (
+        e.eventType === "marker" &&
+        e.data?.markerId &&
+        transcriptionsByMarkerId.has(e.data.markerId)
+      ) {
         return {
           ...e,
           data: {
@@ -1306,8 +1337,7 @@ server.tool(
         },
         {
           tool: "get_live_screenshot",
-          description:
-            "Capture a screenshot of the tester's current browser tab.",
+          description: "Capture a screenshot of the tester's current browser tab.",
         },
       ];
       if (pendingQuestions.length > 0) {
@@ -1319,7 +1349,10 @@ server.tool(
       }
     } else {
       // Session ended — include full interaction log and voice transcriptions
-      if (liveInteractions.length > 0 || liveEvents.some((e) => e.eventType === "voice-transcription")) {
+      if (
+        liveInteractions.length > 0 ||
+        liveEvents.some((e) => e.eventType === "voice-transcription")
+      ) {
         responseData.sessionEndedNote =
           "Session has ended. The interactionLog and voiceMarkerTranscriptions below contain all agent-tester exchanges from this session. " +
           "Include these in your analysis — they represent collaborative context between agent and tester. " +
@@ -1353,20 +1386,29 @@ server.tool(
 );
 
 // Tool: ask_tester_question
-server.tool(
+server.registerTool(
   "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?'",
-      ),
+    description:
+      "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.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+    inputSchema: z.object({
+      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) {
@@ -1425,16 +1467,25 @@ server.tool(
 );
 
 // Tool: get_tester_response
-server.tool(
+server.registerTool(
   "get_tester_response",
-  "Check for the tester's response to a question asked during live shadowing. " +
-    "Returns the tester's screenshot, highlight captures, and transcribed voice note.\n\n" +
-    "IMPORTANT: The tester needs time to record their answer (10-60 seconds). " +
-    "Instead of calling this tool repeatedly, prefer polling watch_live_session — " +
-    "you will see a 'question-response-received' event when the response arrives. " +
-    "Then call this tool once to get the full response with transcription and images.",
   {
-    question_id: z.string().describe("The question ID returned by ask_tester_question."),
+    description:
+      "Check for the tester's response to a question asked during live shadowing. " +
+      "Returns the tester's screenshot, highlight captures, and transcribed voice note.\n\n" +
+      "IMPORTANT: The tester needs time to record their answer (10-60 seconds). " +
+      "Instead of calling this tool repeatedly, prefer polling watch_live_session — " +
+      "you will see a 'question-response-received' event when the response arrives. " +
+      "Then call this tool once to get the full response with transcription and images.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({
+      question_id: z.string().describe("The question ID returned by ask_tester_question."),
+    }),
   },
   async ({ question_id }) => {
     const response = questionResponses.get(question_id);
@@ -1448,8 +1499,7 @@ server.tool(
           {
             type: "text",
             text: [
-              "No response yet." +
-                (waitingSec !== null ? ` Waiting for ${waitingSec}s.` : ""),
+              "No response yet." + (waitingSec !== null ? ` Waiting for ${waitingSec}s.` : ""),
               "The tester may still be recording their voice answer.",
               "",
               "TIP: Instead of polling this tool, go back to polling watch_live_session — " +
@@ -1552,10 +1602,19 @@ server.tool(
 );
 
 // Tool: get_live_screenshot
-server.tool(
+server.registerTool(
   "get_live_screenshot",
-  "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
-  {},
+  {
+    description:
+      "Capture a screenshot of the tester's current browser tab during a live shadowing session.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+  },
   async () => {
     if (!liveSessionActive || !activeConnection) {
       return toolError("No active live shadowing session or extension not connected.");
@@ -1606,13 +1665,22 @@ server.tool(
 );
 
 // Tool: get_live_session_summary
-server.tool(
+server.registerTool(
   "get_live_session_summary",
-  "Get a summary of the live shadowing session including all agent-tester interactions. " +
-    "Call this after the session ends (sessionActive becomes false) to get the complete interaction log " +
-    "for incorporating into your analysis. This includes all questions asked, tester responses, " +
-    "voice transcriptions, and voice marker transcriptions from the session.",
-  {},
+  {
+    description:
+      "Get a summary of the live shadowing session including all agent-tester interactions. " +
+      "Call this after the session ends (sessionActive becomes false) to get the complete interaction log " +
+      "for incorporating into your analysis. This includes all questions asked, tester responses, " +
+      "voice transcriptions, and voice marker transcriptions from the session.",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: z.object({}),
+  },
   async () => {
     if (!liveSessionMeta && liveInteractions.length === 0) {
       return toolError("No live session data available. Start a live shadowing session first.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracegist-mcp-bridge",
-  "version": "0.2.8",
+  "version": "0.2.12",
   "description": "Local-first MCP bridge for reading and transcribing TraceGist package zips.",
   "type": "module",
   "bin": {