tracegist-mcp-bridge 0.2.6 → 0.2.7

package/bin/tracegist-mcp-bridge.mjs

@@ -866,6 +866,14 @@ const pendingQuestions = [];
 /** @type {Map<string, object>} */
 const questionResponses = new Map();
 
+/**
+ * Persistent log of all agent-tester interactions during the live session.
+ * Survives until the next session-start. Used to build the complete interaction
+ * history for the final artifact.
+ * @type {Array<{type: string, questionId: string, question?: string, timestamp: number, transcription?: string, screenshot?: boolean, highlightCount?: number, dismissed?: boolean}>}
+ */
+const liveInteractions = [];
+
 /** @type {Array<{resolve: Function, reject: Function, timeout: ReturnType<typeof setTimeout>}>} */
 const screenshotWaiters = [];
 
@@ -1039,6 +1047,7 @@ function handleExtensionMessage(msg) {
       liveEvents.length = 0;
       pendingQuestions.length = 0;
       questionResponses.clear();
+      liveInteractions.length = 0;
       console.error(`[${BRIDGE_NAME}] Live shadow: session started (${msg.sessionId})`);
       // Notify MCP clients that resources changed
       try {
@@ -1072,6 +1081,14 @@ function handleExtensionMessage(msg) {
       });
       const rIdx = pendingQuestions.findIndex((q) => q.questionId === msg.questionId);
       if (rIdx >= 0) pendingQuestions.splice(rIdx, 1);
+      // Push a live event so polling agents see the response immediately
+      pushLiveEvent("question-response-received", {
+        questionId: msg.questionId,
+        hasVoice: !!msg.voiceBlobDataUrl,
+        hasScreenshot: !!msg.screenshot,
+        highlightCount: msg.highlightCaptures?.length || 0,
+        hint: "Use get_tester_response to retrieve the full response with transcription and images.",
+      });
       break;
     }
 
@@ -1079,6 +1096,14 @@ function handleExtensionMessage(msg) {
       questionResponses.set(msg.questionId, { dismissed: true });
       const dIdx = pendingQuestions.findIndex((q) => q.questionId === msg.questionId);
       if (dIdx >= 0) pendingQuestions.splice(dIdx, 1);
+      // Log dismissal in interactions
+      liveInteractions.push({
+        type: "question-dismissed",
+        questionId: msg.questionId,
+        timestamp: Date.now(),
+        dismissed: true,
+      });
+      pushLiveEvent("question-dismissed", { questionId: msg.questionId });
       break;
     }
 
@@ -1099,6 +1124,13 @@ function handleExtensionMessage(msg) {
             transcription: result.transcription || null,
             error: result.error || undefined,
           });
+          // Log voice marker in interactions for the final artifact
+          liveInteractions.push({
+            type: "voice-marker",
+            questionId: markerId,
+            timestamp: Date.now(),
+            transcription: result.transcription || null,
+          });
         })
         .catch((err) => {
           console.error(`[${BRIDGE_NAME}] Live voice transcription failed:`, err);
@@ -1151,9 +1183,14 @@ server.resource(
 // 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.",
+  "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.\n" +
+    "- The tester may set voice markers at any time to communicate with you — keep watching for them.\n" +
+    "- Only stop polling when sessionActive is false (the recording ended).",
   {
     since_seq: z
       .number()
@@ -1172,37 +1209,56 @@ server.tool(
 
     const latestSeq = liveEvents.length > 0 ? liveEvents[liveEvents.length - 1].seq : 0;
 
+    const responseData = {
+      sessionActive: liveSessionActive,
+      session: liveSessionMeta,
+      events,
+      latestSeq,
+      eventCount: events.length,
+    };
+
+    if (liveSessionActive) {
+      responseData.pollingGuidance =
+        "KEEP POLLING every 2-4 seconds. Do NOT stop — the tester is still active. " +
+        "Watch for 'voice-transcription' events (tester voice markers) and 'question-response-received' events. " +
+        "React to voice markers by acknowledging them or asking follow-up questions.";
+      responseData.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.",
+        },
+      ];
+      if (pendingQuestions.length > 0) {
+        responseData.pendingQuestions = pendingQuestions.map((q) => ({
+          questionId: q.questionId,
+          question: q.question,
+          waitingSince: Math.round((Date.now() - q.sentAt) / 1000) + "s ago",
+        }));
+      }
+    } else if (liveInteractions.length > 0) {
+      // Session ended — include full interaction log for the agent to incorporate
+      responseData.sessionEndedNote =
+        "Session has ended. The interactionLog below contains all agent-tester exchanges from this session. " +
+        "Include these in your analysis — they represent collaborative context between agent and tester.";
+      responseData.interactionLog = liveInteractions;
+    }
+
+    // Always include interaction count so the agent knows exchanges happened
+    if (liveInteractions.length > 0) {
+      responseData.interactionCount = liveInteractions.length;
+    }
+
     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,
-          ),
+          text: JSON.stringify(responseData, null, 2),
         },
       ],
     };
@@ -1248,6 +1304,17 @@ server.tool(
       pendingQuestions.shift();
     }
 
+    // Log the interaction
+    liveInteractions.push({
+      type: "agent-question",
+      questionId,
+      question,
+      timestamp: Date.now(),
+    });
+
+    // Push a live event so the polling loop sees it
+    pushLiveEvent("agent-question-sent", { questionId, question });
+
     return {
       content: [
         {
@@ -1260,7 +1327,9 @@ server.tool(
             "- 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.",
+            "IMPORTANT: Keep polling watch_live_session — you will see a 'question-response-received' event when they respond.",
+            "Then use `get_tester_response` with this question ID to retrieve their full answer.",
+            "The tester may take 10-30 seconds to record their voice response. Be patient.",
           ].join("\n"),
         },
       ],
@@ -1272,7 +1341,11 @@ server.tool(
 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.",
+    "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."),
   },
@@ -1280,11 +1353,22 @@ server.tool(
     const response = questionResponses.get(question_id);
 
     if (!response) {
+      // Check how long we've been waiting
+      const pending = pendingQuestions.find((q) => q.questionId === question_id);
+      const waitingSec = pending ? Math.round((Date.now() - pending.sentAt) / 1000) : null;
       return {
         content: [
           {
             type: "text",
-            text: "No response yet. The tester may still be recording their answer. Try again in a few seconds.",
+            text: [
+              "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 — " +
+                "a 'question-response-received' event will appear when the tester responds. " +
+                "Then call this tool once to retrieve the full answer.",
+            ].join("\n"),
           },
         ],
       };
@@ -1344,9 +1428,11 @@ server.tool(
       }
     }
 
+    let transcriptionText = null;
     if (response.voiceBlobDataUrl) {
       const voiceResult = await transcribeLiveVoice(response.voiceBlobDataUrl);
       if (voiceResult.transcription) {
+        transcriptionText = voiceResult.transcription;
         content.push({
           type: "text",
           text: `Voice transcription:\n${voiceResult.transcription}`,
@@ -1359,6 +1445,21 @@ server.tool(
       }
     }
 
+    // Log the interaction for the session history
+    liveInteractions.push({
+      type: "tester-response",
+      questionId: question_id,
+      timestamp: Date.now(),
+      transcription: transcriptionText,
+      screenshot: !!response.screenshot,
+      highlightCount: response.highlightCaptures?.length || 0,
+    });
+
+    content.push({
+      type: "text",
+      text: "\nIMPORTANT: Resume polling watch_live_session to continue watching the session.",
+    });
+
     // Clean up after retrieval
     questionResponses.delete(question_id);
 
@@ -1420,6 +1521,50 @@ server.tool(
   },
 );
 
+// Tool: get_live_session_summary
+server.tool(
+  "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.",
+  {},
+  async () => {
+    if (!liveSessionMeta && liveInteractions.length === 0) {
+      return toolError("No live session data available. Start a live shadowing session first.");
+    }
+
+    // Collect voice-transcription events from the event buffer
+    const voiceTranscriptions = liveEvents
+      .filter((e) => e.eventType === "voice-transcription" && e.data?.transcription)
+      .map((e) => ({
+        timestamp: e.ts,
+        markerId: e.data.markerId,
+        transcription: e.data.transcription,
+      }));
+
+    const summary = {
+      session: liveSessionMeta,
+      sessionActive: liveSessionActive,
+      interactionLog: liveInteractions,
+      voiceMarkerTranscriptions: voiceTranscriptions,
+      totalEvents: liveEvents.length,
+      guidance: liveSessionActive
+        ? "Session is still active. Resume polling watch_live_session."
+        : "Session has ended. Use this interaction log and voice transcriptions to enrich your analysis of the exported session package.",
+    };
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(summary, null, 2),
+        },
+      ],
+    };
+  },
+);
+
 // ---------------------------------------------------------------------------
 // Startup
 // ---------------------------------------------------------------------------

package/package.json

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