@usercase/mcp 0.2.11-next.0 → 0.2.11-next.2

package/agents/fix.md

@@ -0,0 +1,36 @@
+# Fix a problem found by a Usercase research
+
+Research: {{research}}
+Finding: {{finding}}
+Report: {{audience}}
+
+A Usercase research watched people (or virtual users) do tasks on this site. Its report lists findings — problems on the site, each backed by what people did, what the screen showed in the recordings, and what they wrote. You fix one finding in this repository's code.
+
+## 1. Read the finding
+
+Call `report_finding` with the research id, the finding key and the report. If no finding key is given above, call `report_findings` first, show the user the list (key, severity, title, and whether someone is already fixing it), and ask which one to fix.
+
+Read all of it: the title and why, who it hit, the screen checks (what the page really showed — these come from the recordings, not from opinions), the paths people took, the groups of what they wrote, and the suggested changes. The suggested changes were written without seeing the code; treat them as a direction, not a spec.
+
+## 2. Find the code
+
+From the pages, buttons and texts in the evidence, find the code behind them: routes, the page components, the button and its click handler, the text shown. Confirm you found the right place by matching the exact text on screen (a button label, a heading) to the code.
+
+## 3. Propose the change — before changing anything
+
+Tell the user, briefly:
+- what in the code causes the problem, with file paths,
+- the change you propose and why it addresses what people did and said, and
+- anything the finding suggests that you would not do, and why (it would break something, it needs a product decision, the code already does it).
+
+Keep the change as small as solves the problem. Do not redesign unrelated parts. Wait for the user's approval or corrections.
+
+## 4. Change the code
+
+When the user approves, call `report_fix` with `status` `fixing` and the files you will change. Then make the change. Follow the repository's own conventions, and run its checks (type check, lint, tests) if it has them.
+
+## 5. Record the fix
+
+When the change is done, call `report_fix` with `status` `fixed`, the files changed, a one-sentence summary written for the team (what a visitor now sees differently), and the pull request link if you opened one. Do not commit, push or open a pull request unless the user asks.
+
+Then tell the user that the finding shows as fixed in the report, and how to check it worked: {{check}}

package/mcp/hub.js

@@ -25,6 +25,7 @@ const ws = require("./workspace.js");
 const signin = require("../src/browser/signin.js");
 const { openRealChrome } = require("../src/browser/real-chrome.js");
 const study = require("../src/browser/study.js");
+const voice = require("../src/browser/voice.js");
 const report = require("./report.js");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -49,7 +50,9 @@ function trace(rec, o) {
     fs.appendFileSync(TRACE, JSON.stringify({ at: Date.now(), person: rec && rec.person ? rec.person.id : null, ...o }) + "\n");
   } catch {}
 }
-const STUDY_ACTIVE = new Set(["consent", "loading", "testing", "timeout", "survey", "next", "submit"]);
+/** 음성 설문이 끝나고 위젯이 간 곳 — 여기면 마지막 말은 인사다 */
+const VOICE_OVER = new Set(["testing", "next", "submit", "loading", "done", "complete", "idle"]);
+const STUDY_ACTIVE = new Set(["consent", "mic", "loading", "testing", "timeout", "survey", "ai", "next", "submit"]);
 
 /**
  * 가상 사용자 표시 이름. 서버가 이 이름으로 가상 사용자 답을 진짜 답과 갈라 센다
@@ -459,7 +462,7 @@ class Hub {
     const sdk = await rec.visit.begin();
     // 리서치 참여 — 초대 수락·녹화 동의까지는 참여하기로 한 사람이 늘 하는 것이라 도구가 한다
     if (research) {
-      rec.study = { research, answers: [], tasks: [], skipped: [], lastTask: null, over: false, surveyAt: null };
+      rec.study = { research, answers: [], tasks: [], skipped: [], lastTask: null, over: false, surveyAt: null, heardFrom: 0 };
       const j = await study.join(page);
       if (!j.ok) {
         await this.finish(rec, { study: { research, failed: j.why } });
@@ -482,6 +485,11 @@ class Hub {
         "You agreed to take part, so you stay with the study until its tasks are done — you do not leave the site in the middle of it over a small thing. The study may ask you a few questions along the way; answer them with answer_card.",
         "If you get stuck on a task, do what a person does: keep looking for it — try other menus and pages, go back, scroll through lists, try what you have not tried yet. Studies usually offer a way to give up on a task after a while; when the panel offers it and you would give up, take it and go on to the next task. Leave in the middle only if you really would — something about you or your moment makes you stop.",
       );
+    // AI 모더레이터 리서치 — 마이크를 받아 갔다(voice.js). 목소리가 말을 걸고, 방문자는 소리 내어 답한다
+    if (research && (await page.evaluate(() => !!(window.__ucVoice && window.__ucVoice.used())).catch(() => false)))
+      lines.push(
+        "This study has a voice: you allowed your microphone, and a voice may talk to you during the study (you see its words as a caption). When it asks you something, you answer out loud — with answer_card.",
+      );
     if (!sdk.ready) lines.push("(note for whoever runs this: the Usercase SDK did not start on this page — this visit may not be recorded)");
     lines.push("", await this.screen(rec));
     return { id, text: lines.join("\n") };
@@ -558,6 +566,17 @@ class Hub {
         await study.waitState(page, ["testing", "survey", "submit", "done"], 15000);
         continue;
       }
+      // AI 모더레이터가 소리로 묻는 중(음성 후속설문). 물음이 들리면 방문자가 소리 내어 답한다
+      if (s.state === "ai") {
+        const q = await this.voiceQuestion(rec);
+        if (q) {
+          rec.studyPending = { kind: "voice", q, task: st.lastTask };
+          return { card: renderVoiceQuestion(q, st.lastTask) };
+        }
+        s = study.isSurveyUrl(page.url()) ? null : await study.readStudy(page);
+        if (!s || s.state === "ai") break;
+        continue;
+      }
       if (s.state === "submit" || s.state === "loading") {
         await study.waitState(page, ["done", "complete", "testing", "survey", "next", "idle", "invite"], 120000);
         continue;
@@ -581,6 +600,14 @@ class Hub {
       }
       st.lastTaskKey = key;
       st.lastTask = s.task.title;
+      // 과제 중에 모더레이터가 한 말(음성 리서치) — 사람도 듣는다
+      // 아직 말하는 중인 줄은 다음 화면에서 — 자막이 늘어나며 이어지는 동안 읽으면 말이 반쯤 잘린다
+      const h = await voice.heard(page, st.heardFrom);
+      if (h && h.closed) {
+        st.heardFrom += h.closed;
+        const said = `(The study's voice said: ${h.lines.slice(0, h.closed).map((l) => `"${l.text}"`).join(" ")})`;
+        note = note ? `${note}\n${said}` : said;
+      }
       // 패널에는 지금 과제에 머문 시간이 보인다(SDK 알약의 타이머) — 방문자도 같은 걸 본다
       const onTaskMs = Date.now() - rec.startedAt - st.tasks[st.tasks.length - 1].at;
       st.canSkip = !!s.task.skip;
@@ -602,6 +629,55 @@ class Hub {
     return null;
   }
 
+  /**
+   * 모더레이터가 소리로 묻는 것(자막). 아직 답하지 않은 새 말이 들릴 때까지 기다린다 — 말이 이어지면 다 들은 뒤.
+   * 위젯이 묻는 상태(ai)를 벗어나거나 한참 조용하면 null
+   */
+  async voiceQuestion(rec, ms = 25000) {
+    const st = rec.study;
+    const page = rec.page;
+    let h = null;
+    for (let t = 0; t < ms; t += 300) {
+      h = await voice.heard(page, st.heardFrom);
+      if (!h) return null;
+      // 설문 전에(과제 중에) 한 말은 묻는 말이 아니다 — 지나간다. 안 그러면 인사에 답하고 답이 한 칸씩 밀린다(11/04 실험실)
+      let skip = 0;
+      while (skip < h.lines.length && h.lines[skip].state !== "ai" && (skip < h.closed || !h.speaking)) skip++;
+      if (skip) {
+        if (TRACE) trace(rec, { ev: "voice_skip", lines: h.lines.slice(0, skip).map((l) => `${l.state}: ${l.text.slice(0, 80)}`) });
+        st.heardFrom += skip;
+        h = await voice.heard(page, st.heardFrom);
+        if (!h) return null;
+      }
+      if (h.lines.length && h.lines[0].state === "ai") break;
+      const s = await study.readStudy(page);
+      if (!s || s.state !== "ai") return null;
+      await sleep(300);
+    }
+    if (!h || !h.lines.length || h.lines[0].state !== "ai") return null;
+    // 말을 다 들을 때까지(자막이 내려갈 때까지). 서버는 질문을 말하기 시작할 때부터 답을 기다리니 너무 오래는 못 듣는다
+    for (let t = 0; t < 10000 && h.speaking; t += 300) {
+      await sleep(300);
+      h = (await voice.heard(page, st.heardFrom)) || h;
+    }
+    // 마지막 인사("고마워요")로 설문이 끝나면 위젯이 곧 묻는 상태를 벗어난다 — 그건 답할 말이 아니다
+    // 끝났다고 보는 건 위젯이 분명히 다음으로 간 때만 — 못 읽었거나 잠깐 바뀌는 중이면 묻는 말로 둔다.
+    // "아니면 끝" 으로 봤더니 진짜 질문을 넘겨 서버가 답 없이 다음으로 갔다(11/04 실험실 p2132)
+    let after = null;
+    for (let t = 0; t < 1500; t += 300) {
+      await sleep(300);
+      after = await study.readStudy(page);
+      if (after && VOICE_OVER.has(after.state)) break;
+    }
+    const text = h.lines.map((l) => l.text).join(" ");
+    if (TRACE) trace(rec, { ev: "voice_q", text: text.slice(0, 120), after: after ? after.state : null });
+    if (after && VOICE_OVER.has(after.state)) {
+      st.heardFrom = h.total;
+      return null;
+    }
+    return { text, upTo: h.total };
+  }
+
   /** 과제 질문·시간 초과 창에 답한다. 참여하기로 한 사람이라 닫지 않는다 — 비워 두고 넘기는 건 된다(필수가 아니면) */
   async studyAnswer(rec, decision) {
     const p = rec.studyPending;
@@ -610,6 +686,31 @@ class Hub {
     // 손이 고른 답으로 가는 시간. 읽고 정하는 건 AI 가 이미 했다(11/02: 1.2~3.7초를 또 기다렸다)
     await sleep(300 + Math.random() * 500);
     let said;
+    if (p.kind === "voice") {
+      // 소리 내어 답한다. 모더레이터가 말을 마칠 때까지 기다린다 — 끼어들지 않는다
+      st.heardFrom = p.q.upTo;
+      const words = decision.action === "other" ? String(decision.otherText || "").trim() : "";
+      for (let t = 0; t < 20000; t += 300) {
+        const h = await voice.heard(page, st.heardFrom);
+        if (!h || !h.speaking) break;
+        await sleep(300);
+      }
+      let answer = null;
+      if (words) {
+        try {
+          await voice.speak(page, words, { seed: rec.person.id });
+          answer = words;
+          said = `You said: "${words}"`;
+        } catch (e) {
+          said = `You tried to answer out loud, but no sound came out (${String(e.message).split("\n")[0]}).`;
+        }
+      } else said = "You stayed quiet and did not answer.";
+      st.answers.push({ task: p.task, question: p.q.text, answer, why: decision.why, spoken: true });
+      rec.studyPending = null;
+      rec.visit.history.push(`The study's voice asked "${p.q.text}" — ${said}`);
+      await sleep(600);
+      return [said, "", await this.screen(rec)].join("\n");
+    }
     if (p.kind === "timeout") {
       const skip = decision.action === "choose" && decision.choiceIndex === 1;
       await study.press(page, skip ? "timeoutSkip" : "keepGoing").catch(() => {});
@@ -1062,6 +1163,18 @@ function renderStudyQuestion(q, task) {
   return L.join("\n");
 }
 
+/** AI 모더레이터가 소리로 묻는다(음성 리서치) */
+function renderVoiceQuestion(q, task) {
+  return [
+    "## The study's voice is asking you something, out loud",
+    `This is part of the study you agreed to take part in${task ? ` (it comes after the task "${task}")` : ""}. A voice speaks to you, and its words show as a caption:`,
+    "",
+    `"${q.text}"`,
+    "",
+    "Answer out loud, as yourself, with answer_card: bothered true, action other, and in other_text exactly what you say — spoken words in the language of the voice, the way this person talks, in one go (a short pause ends your answer). It waits for you only a few seconds, so answer right away. Close only if you would stay quiet.",
+  ].join("\n");
+}
+
 /** 과제에 시간이 오래 걸리면 패널이 묻는다 */
 function renderStudyTimeout(t, task) {
   return [

package/mcp/report.js

@@ -292,6 +292,11 @@ const sendSteps = (session, body) => keyed("PUT", `/agent/questions/steps/${enco
 /** 리서치 초안(new-research) — 무엇을 리서치할지 고를 근거와, Inbox 초안으로 저장 */
 const getResearchContext = () => keyed("GET", "/agent/researches/context", null, 30000);
 const saveResearchDraft = (body) => keyed("POST", "/agent/researches/drafts", body, 30000);
+/** 리서치 Report(fix) — 발견 목록, 발견 하나와 근거, 고친 기록 */
+const rq = (audience) => (audience === "real" ? "?audience=real" : "?audience=virtual");
+const getReport = (researchId, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report${rq(audience)}`);
+const getFinding = (researchId, key, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}${rq(audience)}`);
+const saveFix = (researchId, key, body) => keyed("PUT", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}/fix`, body);
 /** 대시보드 주소. API 주소에서 /koa 를 뗀다 */
 const dashboardUrl = (p) => apiBase().replace(/\/koa$/, "") + p;
 
@@ -315,5 +320,8 @@ module.exports = {
   sendSteps,
   getResearchContext,
   saveResearchDraft,
+  getReport,
+  getFinding,
+  saveFix,
   dashboardUrl,
 };

package/mcp/server.js

@@ -556,6 +556,87 @@ server.registerTool(
 
 const recorder = new PathRecorder(hub);
 
+// ── 리서치 Report 의 발견 고치기(fix) ──
+const audienceArg = z.enum(["virtual", "real"]).optional().describe("Which report: virtual users (default) or real people");
+const fixLine = (f) => (f ? ` — ${f.status === "fixed" ? "fixed" : "being fixed"}${f.agent ? ` by ${f.agent}` : ""}` : "");
+const whoWord = (audience) => (audience === "real" ? "people" : "virtual users");
+
+server.registerTool(
+  "report_findings",
+  {
+    description:
+      "List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key.",
+    inputSchema: { research: z.string().describe("The research id"), audience: audienceArg },
+  },
+  wrap(async ({ research, audience }) => {
+    const r = await report.getReport(research, audience);
+    if (!r.findings)
+      return text(r.making ? "The report is being written right now. Try again in a minute." : `This research has no ${whoWord(r.audience)} report yet. It is written once 5 have finished.`);
+    return text(
+      [
+        `${r.research.title} — report of ${r.people} ${whoWord(r.audience)}`,
+        `Summary: ${r.summary}`,
+        "",
+        ...r.findings.map((f) => `${f.key} [${f.severity}] ${f.title} — ${f.who}${fixLine(f.fix)}`),
+        "",
+        `Report: ${r.url}`,
+      ].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "report_finding",
+  {
+    description:
+      "Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code.",
+    inputSchema: { research: z.string().describe("The research id"), finding: z.string().describe("Finding key, e.g. F1"), audience: audienceArg },
+  },
+  wrap(async ({ research, finding, audience }) => {
+    const r = await report.getFinding(research, finding, audience);
+    const f = r.finding;
+    const e = r.evidence;
+    const L = [
+      `${f.key} [${f.severity}] ${f.title}${fixLine(f.fix)}`,
+      `Research: ${r.research.title} (report of ${r.people} ${whoWord(r.audience)})`,
+      "",
+      `Why: ${f.why}`,
+      `Who: ${f.who}`,
+      `Where: ${f.where}`,
+    ];
+    if (e.screen.length) L.push("", "What the screen showed (from the recordings):", ...e.screen.map((x) => `- ${x.replace(/^Screen check:\s*/, "")}`));
+    if (e.paths.length) L.push("", "Paths people took:", ...e.paths.map((p) => `- ${(p.steps || []).join(" → ")} (${p.people} people)`));
+    if (e.words.length) L.push("", "What people wrote (grouped by meaning, with examples):", ...e.words.map((w) => `- ${w.text}`));
+    if (e.numbers.length) L.push("", "Numbers:", ...e.numbers.map((x) => `- ${x}`));
+    L.push("", "Suggested changes (written without seeing the code):", ...f.changes.map((c, i) => `${i + 1}. ${c}`), `Check after the fix: ${f.measure}`);
+    if (r.sessionsUrl) L.push("", `Watch these sessions: ${r.sessionsUrl}`);
+    L.push(`Report: ${r.reportUrl}`);
+    return text(L.join("\n"));
+  }),
+);
+
+server.registerTool(
+  "report_fix",
+  {
+    description:
+      "Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). The report shows it on that finding.",
+    inputSchema: {
+      research: z.string().describe("The research id"),
+      finding: z.string().describe("Finding key, e.g. F1"),
+      audience: audienceArg,
+      status: z.enum(["fixing", "fixed"]),
+      files: z.array(z.string()).optional().describe("Repository paths of the files changed (or to be changed)"),
+      summary: z.string().optional().describe("One sentence for the team: what visitors now see differently"),
+      prUrl: z.string().optional().describe("Pull request link, if one was opened"),
+    },
+  },
+  wrap(async ({ research, finding, audience, status, files, summary, prUrl }) => {
+    const agent = CODEX ? "Codex" : OTHER ? null : "Claude Code";
+    const r = await report.saveFix(research, finding, { audience: audience || "virtual", status, agent, files, summary, prUrl });
+    return text(`${r.key} is marked ${r.status} on the report: ${r.reportUrl}`);
+  }),
+);
+
 server.registerTool(
   "path_tasks",
   {
@@ -1047,6 +1128,21 @@ const COMMANDS = {
         "Only this repository's folder changes. Other repositories keep their own project. Until the new project is approved, the current connection stays.",
       ].join("\n"),
   },
+  // 리서치 Report 의 발견 하나를 고친다 — 대시보드 Report 의 "Fix with your agent" 명령
+  fix: {
+    description: "Fix a finding from a Usercase research report in this repository's code",
+    argsSchema: { research: z.string().optional(), finding: z.string().optional(), audience: z.string().optional() },
+    body: ({ research, finding, audience }) =>
+      agentDoc("fix.md", {
+        research: research || "(ask the user — the dashboard Report shows the command)",
+        finding: finding ? String(finding).toUpperCase() : "(not given — list the findings and ask)",
+        audience: audience === "real" ? "real (the report of real people)" : "virtual (the report of virtual users)",
+        check:
+          audience === "real"
+            ? "the next report, made as more people take part, shows whether people still hit it."
+            : `run the same tasks with virtual users again (${cmd("research")} <site> 5 research=${research || "<research id>"}). The next report shows whether they still hit it.`,
+      }),
+  },
   steps: {
     description: "Write the steps for the question open in your dashboard (New question → Several steps)",
     argsSchema: { session: z.string().optional().describe("The window id shown in the dashboard command") },
@@ -1059,12 +1155,13 @@ if (PLUGIN || CODEX || OTHER) {
     "instructions",
     {
       description:
-        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
+        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect, fix). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
       inputSchema: {
         command: z.enum(Object.keys(COMMANDS)),
         ...COMMANDS.research.argsSchema,
         ...COMMANDS.path.argsSchema,
         ...COMMANDS.steps.argsSchema,
+        ...COMMANDS.fix.argsSchema,
       },
     },
     wrap(async ({ command, ...args }) => text(COMMANDS[command].body(byName(args, COMMANDS[command].argsSchema)))),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.11-next.0",
+  "version": "0.2.11-next.2",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",

package/src/browser/open.js

@@ -11,6 +11,7 @@
  */
 
 const { markAgent, withAgentUA } = require("./card.js");
+const { installVoice } = require("./voice.js");
 
 /** HTTPS 사이트에서 localhost SDK·소켓을 부르려면 사설망 제한을 꺼야 한다. 로컬 SDK 로 돌릴 때만 필요하다 */
 const LOCAL_NETWORK_ARGS = ["--disable-features=LocalNetworkAccessChecks,PrivateNetworkAccessSendPreflights,PrivateNetworkAccessRespectPreflightResults"];
@@ -54,6 +55,8 @@ async function openVisit(browser, devices, { agent, site, guard, device = "deskt
   await guard.apply(ctx, { onOffsite, onWrite, onExternal });
   // **반드시 guard 뒤.** markAgent 의 비밀값 route 가 마지막에 걸려야 먼저 돈다
   await markAgent(ctx, agent, { siteOrigin: site, persona, research, debugCards, hideDevOverlay: guard.local });
+  // 리서치 참여자는 목소리를 가진다 — AI 모더레이터 리서치가 마이크를 달라면 우리 목소리를 준다(voice.js)
+  if (research) await installVoice(ctx);
   return ctx;
 }
 

package/src/browser/study.js

@@ -8,7 +8,8 @@
  * 질문에 무엇을 답하는지, 포기할지는 방문자가 정한다.
  *
  * 화면 구성(earningbirds-core layouts/Widget.ts · components/frost/*):
- *   #eb-pill[data-state] — idle·invite·consent·loading·testing·timeout·survey·next·submit·done …
+ *   #eb-pill[data-state] — idle·invite·consent·mic·loading·testing·timeout·survey·ai·next·submit·done …
+ *   mic: #eb-mic-start(음성 리서치의 마이크 확인) · ai: AI 모더레이터가 소리로 묻는 중(자막은 voice.js 가 읽는다)
  *   #eb-frost(.eb-visible 이면 열림) > #eb-frost-body
  *   testing: .eb-frost-testing .eb-gf-section(진행) .eb-gf-flat-title(과제) .eb-gf-flat-sub(설명) #eb-task-lefttime-text #eb-test-skip
  *   timeout: .eb-frost-timeout #eb-timeout-continue #eb-timeout-skip
@@ -152,7 +153,21 @@ async function join(page, { inviteMs = 25000 } = {}) {
     await sleep(1500 + Math.random() * 2500);
     await page.locator("#eb-plugin #eb-consent-agree").click({ timeout: 5000 }).catch(() => {});
   }
-  const s = await waitState(page, ["testing", "survey", "done"], 40000);
+  let s = await waitState(page, ["mic", "testing", "survey", "done"], 40000);
+  // AI 모더레이터(음성) 리서치는 동의 뒤 마이크 확인 화면이 있다. 마이크는 voice.js 가 준 우리 목소리다 —
+  // 연결됐다고 뜨면 사람처럼 잠깐 보고 시작을 누른다. Gemini 를 여는 데 시간이 걸려 시작까지 넉넉히 기다린다
+  if (s && s.state === "mic") {
+    const ready = await page
+      .locator("#eb-plugin #eb-mic-start:not([disabled])")
+      .first()
+      .waitFor({ timeout: 15000 })
+      .then(() => true)
+      .catch(() => false);
+    if (!ready) return { ok: false, why: "the study's microphone check did not accept the virtual user's microphone" };
+    await sleep(1200 + Math.random() * 1800);
+    await page.locator("#eb-plugin #eb-mic-start").first().click({ timeout: 5000 }).catch(() => {});
+    s = await waitState(page, ["testing", "survey", "done"], 60000);
+  }
   if (!s || s.state !== "testing") return { ok: false, why: `the research did not start (the study panel is at "${s ? s.state || "?" : "nothing"}")` };
   return { ok: true, study: s };
 }

package/src/browser/voice.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * 가상 사용자의 목소리 — AI 모더레이터(음성) 리서치에 참여할 때.
+ *
+ * 사람 참여자와 같은 길로 간다: SDK 는 마이크를 받고, 그 마이크로 들어온 소리를 Gemini·서버 음성 인식이 듣는다.
+ * - 귀: 모더레이터가 하는 말은 위젯 자막(.eb-ai-caption-text, core components/widget/Widget.ts)으로 뜬다. 그것을 읽는다
+ * - 입: 페이지의 마이크 요청(getUserMedia)이 진짜 마이크 대신 우리가 만든 오디오 줄(MediaStreamDestination)을 받는다.
+ *   할 말은 이 컴퓨터에 깔린 음성(Windows 음성 · macOS say · espeak)으로 wav 를 만들어 그 줄로 튼다 — 바깥 서비스·비용 없음
+ *
+ * 리서치 참여 방문에만 건다(open.js). 음성을 안 쓰는 리서치는 마이크를 부르지 않으니 아무 일도 없다.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFile } = require("child_process");
+
+/** 페이지가 뜨기 전에 심는다. 마이크·권한·장치 목록을 우리 오디오 줄로 바꾸고, 모더레이터 자막을 적어 둔다 */
+const PAGE_SCRIPT = `(() => {
+  if (window.__ucVoice) return;
+  const md = navigator.mediaDevices;
+  if (!md || !md.getUserMedia) return;
+  let ac = null;
+  let dest = null;
+  const line = () => {
+    if (!ac) {
+      ac = new (window.AudioContext || window.webkitAudioContext)();
+      dest = ac.createMediaStreamDestination();
+    }
+    if (ac.state === "suspended") ac.resume().catch(() => {});
+    return dest;
+  };
+  const MIC = { deviceId: "usercase-voice", groupId: "usercase-voice", kind: "audioinput", label: "Microphone" };
+  MIC.toJSON = () => ({ deviceId: MIC.deviceId, groupId: MIC.groupId, kind: MIC.kind, label: MIC.label });
+  const enumerate = md.enumerateDevices ? md.enumerateDevices.bind(md) : async () => [];
+  md.enumerateDevices = async () => {
+    const list = await enumerate().catch(() => []);
+    return [MIC, ...list.filter((d) => d.kind !== "audioinput")];
+  };
+  const gum = md.getUserMedia.bind(md);
+  md.getUserMedia = async (c) => {
+    if (c && c.audio && !c.video) {
+      const d = line();
+      // 받는 쪽이 트랙을 멈춰도(stop) 원본 줄은 살아 있게 복제해 준다
+      return new MediaStream(d.stream.getAudioTracks().map((t) => t.clone()));
+    }
+    return gum(c);
+  };
+  if (navigator.permissions && navigator.permissions.query) {
+    const query = navigator.permissions.query.bind(navigator.permissions);
+    navigator.permissions.query = (p) =>
+      p && p.name === "microphone"
+        ? Promise.resolve({ name: "microphone", state: "granted", onchange: null, addEventListener() {}, removeEventListener() {} })
+        : query(p);
+  }
+  // 모더레이터 자막. 보이는 동안이 말하는 동안이다. 글이 늘어나며 이어지면(스트리밍 자막) 한 줄로 친다
+  const heard = [];
+  let shownText = "";
+  let speaking = false;
+  setInterval(() => {
+    const host = document.getElementById("eb-plugin");
+    const root = (host && host.shadowRoot) || document;
+    const box = root.querySelector(".eb-ai-caption.eb-ai-caption-visible .eb-ai-caption-text");
+    const t = box ? (box.innerText || box.textContent || "").replace(/\\s+/g, " ").trim() : "";
+    speaking = !!t;
+    if (!t || t === shownText) return;
+    // 그 말이 나올 때 위젯 상태 — ai 면 소리로 묻는 설문(답을 기다린다), 그 밖(과제 중)은 그냥 하는 말이다
+    const pill = root.querySelector("#eb-pill");
+    const state = (pill && pill.getAttribute("data-state")) || "";
+    const last = heard[heard.length - 1];
+    if (last && shownText && t.startsWith(shownText)) {
+      last.text = t;
+      last.at = Date.now();
+    } else heard.push({ n: heard.length, text: t, at: Date.now(), state });
+    shownText = t;
+  }, 200);
+  window.__ucVoice = {
+    used: () => !!ac,
+    // closed: 다 말한 줄 수(from 부터). 말하는 중인 마지막 줄은 아직 늘어날 수 있다
+    heard: (from) => {
+      const lines = heard.slice(from || 0);
+      return { speaking, lines, total: heard.length, closed: speaking && lines.length ? lines.length - 1 : lines.length };
+    },
+    say: async (b64) => {
+      const d = line();
+      if (ac.state !== "running") await ac.resume().catch(() => {});
+      const bin = atob(b64);
+      const buf = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) buf[i] = bin.charCodeAt(i);
+      const audio = await ac.decodeAudioData(buf.buffer);
+      const src = ac.createBufferSource();
+      src.buffer = audio;
+      src.connect(d);
+      await new Promise((r) => {
+        src.onended = r;
+        src.start();
+      });
+      return audio.duration;
+    },
+  };
+})();`;
+
+/** 방문 컨텍스트에 목소리를 건다. 페이지보다 먼저 */
+async function installVoice(ctx) {
+  await ctx.addInitScript({ content: PAGE_SCRIPT });
+}
+
+/** 글의 언어. 이 컴퓨터 음성을 고르는 데만 쓴다 */
+function langOf(text) {
+  const s = String(text || "");
+  if (/[가-힣]/.test(s)) return "ko";
+  if (/[぀-ヿ]/.test(s)) return "ja";
+  if (/[一-鿿]/.test(s)) return "zh";
+  if (/[Ѐ-ӿ]/.test(s)) return "ru";
+  return "en";
+}
+
+const run = (cmd, args, ms = 30000) =>
+  new Promise((resolve, reject) =>
+    execFile(cmd, args, { timeout: ms, windowsHide: true, maxBuffer: 4 << 20 }, (err, stdout, stderr) =>
+      err ? reject(new Error(String(stderr || err.message).trim().split("\n")[0])) : resolve(String(stdout)),
+    ),
+  );
+
+/** 사람마다 같은 목소리 — 같은 언어 음성이 여럿이면 사람 번호로 하나를 고정해 고른다 */
+const pickIndex = (seed, n) => {
+  let h = 0;
+  for (const c of String(seed || "")) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+  return n ? h % n : 0;
+};
+
+async function synthWindows(textFile, out, lang, seed) {
+  const ps = [
+    "$ErrorActionPreference='Stop'",
+    "Add-Type -AssemblyName System.Speech",
+    "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer",
+    `$v = @($s.GetInstalledVoices() | Where-Object { $_.Enabled -and $_.VoiceInfo.Culture.Name -like '${lang}*' })`,
+    `if ($v.Count -gt 0) { $s.SelectVoice($v[${pickIndex(seed, 97)} % $v.Count].VoiceInfo.Name) }`,
+    `$s.SetOutputToWaveFile('${out.replace(/'/g, "''")}')`,
+    `$s.Speak([IO.File]::ReadAllText('${textFile.replace(/'/g, "''")}', [Text.Encoding]::UTF8))`,
+    "$s.Dispose()",
+  ].join("; ");
+  await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps]);
+}
+
+async function synthMac(textFile, out, lang, seed) {
+  // say -v '?' : "Yuna   ko_KR   # 안녕하세요" — 그 언어 음성 이름들
+  let voice = null;
+  try {
+    const names = (await run("say", ["-v", "?"]))
+      .split("\n")
+      .map((l) => l.match(/^(.+?)\s+([a-z]{2})[_-][A-Z]{2}\s+#/))
+      .filter((m) => m && m[2] === lang)
+      .map((m) => m[1].trim());
+    if (names.length) voice = names[pickIndex(seed, names.length)];
+  } catch {
+    // 목록을 못 읽으면 기본 음성
+  }
+  await run("say", [...(voice ? ["-v", voice] : []), "--file-format=WAVE", "--data-format=LEI16@22050", "-o", out, "-f", textFile]);
+}
+
+async function synthLinux(textFile, out, lang) {
+  for (const cmd of ["espeak-ng", "espeak"]) {
+    try {
+      await run(cmd, ["-v", lang, "-w", out, "-f", textFile]);
+      return;
+    } catch (e) {
+      if (!/ENOENT|not found/i.test(e.message)) throw e;
+    }
+  }
+  throw new Error("no speech voice on this computer (install espeak-ng)");
+}
+
+/**
+ * 문장 사이 쉼을 줄인다. 서버 음성 인식은 0.7초 조용하면 답이 끝난 것으로 친다(server voiceConfig speechEndTimeoutSec) —
+ * 이 컴퓨터 음성은 문장마다 그보다 길게 쉬어서 두 문장째가 잘린다. 16비트 PCM wav 만 고친다(그 밖은 그대로)
+ */
+function tightenPauses(wav, { maxGapSec = 0.3, floor = 400 } = {}) {
+  if (wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF" || wav.toString("ascii", 8, 12) !== "WAVE") return wav;
+  let off = 12;
+  let fmt = null;
+  while (off + 8 <= wav.length) {
+    const id = wav.toString("ascii", off, off + 4);
+    const size = wav.readUInt32LE(off + 4);
+    if (id === "fmt ") fmt = { channels: wav.readUInt16LE(off + 10), rate: wav.readUInt32LE(off + 12), bits: wav.readUInt16LE(off + 22) };
+    if (id === "data") {
+      if (!fmt || fmt.bits !== 16) return wav;
+      const frame = 2 * fmt.channels;
+      const start = off + 8;
+      const end = Math.min(wav.length, start + size);
+      const maxGap = Math.round(maxGapSec * fmt.rate) * frame;
+      const out = [];
+      let run = 0; // 이어진 조용한 바이트
+      for (let i = start; i + frame <= end; i += frame) {
+        let loud = false;
+        for (let c = 0; c < fmt.channels; c++) if (Math.abs(wav.readInt16LE(i + 2 * c)) > floor) loud = true;
+        run = loud ? 0 : run + frame;
+        if (run <= maxGap) out.push(wav.subarray(i, i + frame));
+      }
+      const data = Buffer.concat(out);
+      const head = Buffer.from(wav.subarray(0, start));
+      head.writeUInt32LE(data.length, off + 4);
+      head.writeUInt32LE(head.length - 8 + data.length, 4);
+      return Buffer.concat([head, data]);
+    }
+    off += 8 + size + (size & 1);
+  }
+  return wav;
+}
+
+/** 할 말을 이 컴퓨터 음성으로 wav 로. @returns Buffer */
+async function synth(text, { seed } = {}) {
+  const lang = langOf(text);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "usercase-voice-"));
+  const textFile = path.join(dir, "say.txt");
+  const out = path.join(dir, "say.wav");
+  try {
+    fs.writeFileSync(textFile, String(text), "utf8");
+    if (process.platform === "win32") await synthWindows(textFile, out, lang, seed);
+    else if (process.platform === "darwin") await synthMac(textFile, out, lang, seed);
+    else await synthLinux(textFile, out, lang);
+    const wav = fs.readFileSync(out);
+    if (wav.length < 100) throw new Error("the voice made no sound");
+    return tightenPauses(wav);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** 소리 내어 말한다 — 끝까지 틀고 돌아온다. @returns 말한 초 */
+async function speak(page, text, opts = {}) {
+  const wav = await synth(text, opts);
+  return page.evaluate((b64) => window.__ucVoice.say(b64), wav.toString("base64"));
+}
+
+/** 모더레이터가 한 말(자막). from 번째 줄부터. 페이지가 아직 안 심겼으면 null */
+async function heard(page, from = 0) {
+  return page.evaluate((f) => (window.__ucVoice ? window.__ucVoice.heard(f) : null), from).catch(() => null);
+}
+
+module.exports = { installVoice, speak, synth, heard, langOf, tightenPauses, PAGE_SCRIPT };