@usercase/mcp 0.2.9 → 0.2.10-next.1

package/agents/study.md

@@ -0,0 +1,26 @@
+## This run takes part in one research: {{research}}
+
+The user wants the people to **take part in a research** from their Usercase dashboard — do its tasks and answer its questions, the way invited participants do — instead of exploring freely. Everything below still applies, with these changes:
+
+**Step 1 — look at the research first.** Right after `check_site`, call `path_tasks` with research `{{research}}`. It shows the research's title, status, purpose and tasks (what the participant is told, and when each task counts as done).
+- If the status is not `deployed`, stop and tell the user: the site only offers deployed researches, so the visitors could not join it. They can deploy it in the dashboard and run this again.
+- If the Usercase SDK is not running on the site, stop — without it there is no research to join.
+
+Show the user the tasks in one short list before casting, so they know what the people will be asked to do.
+
+**Step 3 — cast participants for this research.** Each person is someone who really comes to this site and who would accept this research's invitation — people its purpose is about. Their `goal` is still their own reason for being on the site, in their own words; **do not write the tasks into the goal or anywhere else**. The visitors read the tasks themselves in the study panel, as real participants do — a visitor told the task by you knows more than a participant would, and the research loses its value.
+- Vary them the way real participants vary: devices, how familiar they are with the site, patience, how carefully they read. Some will finish every task, some will get stuck — that is what the research is for.
+- Give each person a `landing` page where the research's invitation would meet them: the page the first task starts from, if the tasks or the code make it clear; otherwise where they would arrive on their own.
+- Pass `research: "{{research}}"` to `save_people`. Only people saved with it take part.
+- Leave out `feature` spreading over the whole feature map — the research decides what the visit is about.
+
+**Step 4 — unchanged.** Each visitor accepts the invitation and agrees to the recording automatically (they are participants who said yes), then does the tasks from the study panel. Do not tell the visitors anything about the research.
+
+If a visitor reports it could not join the research, stop starting new ones, call `check_site`, and tell the user what the visitor said.
+
+**Step 5 — report the research first.** From each visit's `Research:` line in `results`:
+- for each task: how many reached it, how many it moved on from by itself (done), how many skipped it or left during it — and where those people were and what they said
+- the answers people gave to the research's questions after the tasks (from the records only)
+- how many finished all tasks, and how many opened the closing questionnaire
+
+These participants are virtual users. Their sessions are stored in the research's results marked as virtual users, separate from real participants — say so in one line.

package/mcp/hub.js

@@ -24,8 +24,13 @@ const { waitForSdk, agentKey, KEY_ENV, KEY_HEADER, AGENT_HEADER, uaWith } = requ
 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 report = require("./report.js");
 
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 리서치가 아직 진행 중인 위젯 상태(core StateManager WidgetState). 이 밖이면 과제가 끝난 것이다 */
+const STUDY_ACTIVE = new Set(["consent", "loading", "testing", "timeout", "survey", "next", "submit"]);
+
 /**
  * 가상 사용자 표시 이름. 서버가 이 이름으로 가상 사용자 답을 진짜 답과 갈라 센다
  * (earningbirds-server insightFindingService.SYNTHETIC_AGENTS). 자유 탐방이라 qa-explore 와 같은 부류다.
@@ -290,13 +295,27 @@ class Hub {
     const notSent = [];
     // 로컬 사이트가 바깥 서버에 닿으려다 끊긴 것(host). 방문자에게 "이 시험 실행에서는 거기 안 닿는다" 로 알린다
     const external = [];
+    // 리서치에 참여하러 온 사람이면 그 리서치. SDK 가 도착하자마자 그 리서치 초대를 띄운다(study.js)
+    const research = p.research || null;
     const ctx = await this.context(s, {
       device: p.device,
       storageState,
       onOffsite: (u) => offsite.push(u),
       onWrite: (k) => notSent.push(k),
       onExternal: (h) => external.push(h),
-      persona: { id: p.id, device: p.device, background: p.background, goal: p.goal, moment: p.moment, attention: p.attention, surveyHabit: p.surveyHabit, writing: p.writing, traits: p.traits, path: "free exploration" },
+      research,
+      persona: {
+        id: p.id,
+        device: p.device,
+        background: p.background,
+        goal: p.goal,
+        moment: p.moment,
+        attention: p.attention,
+        surveyHabit: p.surveyHabit,
+        writing: p.writing,
+        traits: p.traits,
+        path: research ? `research participant (${research})` : "free exploration",
+      },
     });
     const page = await ctx.newPage();
     s.blockWatch.watch(page, s.origin);
@@ -310,6 +329,22 @@ class Hub {
         // 그걸 갈 곳으로 적으면 "chromewebdata 라는 다른 사이트" 로 안내됐다(10/14 실험실 p22)
         if (noted || !/^https?:/i.test(u || "")) return;
         noted = true;
+        // 리서치의 끝난 뒤 설문. SDK 가 새 탭으로 연다(누르지 않아도, Done 을 눌러도 — 두 번 올 수 있다).
+        // 참여자는 그 탭으로 옮겨 가 설문을 한다 — 방문은 한 탭이라 보던 탭을 그 주소로 옮긴다(한 번만)
+        if (research && study.isSurveyUrl(u)) {
+          pop.close().catch(() => {});
+          if (rec.study && !rec.study.surveyAt) {
+            rec.study.surveyAt = Date.now();
+            const going = page
+              .goto(u, { waitUntil: "domcontentloaded", timeout: 30000 })
+              .catch(() => {})
+              .finally(() => {
+                if (page.__ebPendingNav === going) page.__ebPendingNav = null;
+              });
+            page.__ebPendingNav = going;
+          }
+          return;
+        }
         let same = false;
         try {
           same = new URL(u).origin === s.origin;
@@ -383,13 +418,49 @@ class Hub {
       }
     }
     rec.account = account ? account.account : null;
-    rec.visit = new Visit(page, p, { rhythm, shape, policy: s.policy, offsite, notSent, external });
+    rec.visit = new Visit(page, p, {
+      rhythm,
+      shape,
+      policy: s.policy,
+      offsite,
+      notSent,
+      external,
+      study: research
+        ? {
+            press: (k) => study.press(page, k),
+            // 과제 질문·시간 초과 창이 페이지를 덮고 있나 — 그 사이 조작은 페이지에 닿지 않는다
+            blocking: async () => {
+              const w = study.isSurveyUrl(page.url()) ? null : await study.readStudy(page);
+              return !!w && (w.state === "survey" || w.state === "timeout");
+            },
+          }
+        : null,
+    });
     const sdk = await rec.visit.begin();
+    // 리서치 참여 — 초대 수락·녹화 동의까지는 참여하기로 한 사람이 늘 하는 것이라 도구가 한다
+    if (research) {
+      rec.study = { research, answers: [], tasks: [], skipped: [], lastTask: null, over: false, surveyAt: null };
+      const j = await study.join(page);
+      if (!j.ok) {
+        await this.finish(rec, { study: { research, failed: j.why } });
+        return {
+          stop: true,
+          text: `This visit could not join the research: ${j.why}.\n\n→ Reply to the coordinator with exactly this, and stop.`,
+        };
+      }
+    }
     const arrived =
       how.how === "direct" ? `You typed the address and landed on ${how.path}.` : `You came from ${how.how} (${how.referer || "a link"}) and landed on ${how.path}.`;
     // **누구인지 먼저.** 이게 없으면 서브에이전트가 이름만 보고 짐작해서 걷는다(9/21 그랬다)
     const lines = [`visit_id: ${id}`, "", "## You", renderPerson(p, { card: true }), "", arrived];
     if (p.member) lines.push("You already have an account here and are signed in.");
+    if (research)
+      lines.push(
+        "",
+        "A small invitation popped up asking you to take part in a short study on this site, and you agreed: you accepted it and allowed your screen to be recorded.",
+        "The study panel in the corner of the screen now shows your first task. Do the tasks as yourself, on the site, in your own way — the panel knows when a task is done and moves on by itself.",
+        "If you get stuck on a task, behave as you would: keep trying, use the panel's Skip when it offers one, or leave. The study may ask you a few questions along the way; answer them 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") };
@@ -398,9 +469,14 @@ class Hub {
   /** 지금 화면(또는 떠 있는 카드)을 에이전트가 읽을 글로 */
   async screen(rec) {
     const v = rec.visit;
+    // 리서치 참여 중이면 위젯부터 본다 — 과제 질문·시간 초과 창은 페이지를 덮고, 방문자가 먼저 답해야 한다
+    const st = rec.study && !v.ended ? await this.studyLook(rec) : null;
+    if (st && st.card) return st.card;
     const look = await v.look();
     if (look.ended) return "This visit has ended.";
     if (look.card) return renderCard(look.card);
+    // 과제 건너뛰기는 위젯 단추다. 화면 목록 끝에 붙인다 — 누르면 Visit 이 위젯을 누른다
+    if (st && st.skip && !look.view.dialog) look.view.items.push({ i: look.view.items.length, label: `${st.skip} (in the study panel — gives up on this task)`, where: "study panel, corner of the screen", study: "skip" });
     // 브라우저 창(confirm 등)이 떠 있다. 페이지는 멈춰 있다 — 아이콘 그림·위치는 안 본다
     if (look.view.dialog) {
       this.pictures.set(rec.id, null);
@@ -418,16 +494,123 @@ class Hub {
     rec.lastY = y;
     rec.lastAt = at;
     rec.lastCover = cover;
+    if (st && st.note) lines.push(st.note, "");
     lines.push(renderScreen(look));
+    if (st && st.panel) lines.push("", st.panel);
     // 이름 없는 아이콘은 그림으로 같이 준다 — 좌표만으로는 사진 첨부와 보내기를 못 갈랐다(10/21 bluetags 2b72)
     const pic = await iconPicture(v.page, look.view.items, await this.browser().catch(() => null)).catch(() => null);
     this.pictures.set(rec.id, pic);
     if (pic) lines.push("(A picture of the unlabelled icons on this screen is attached — each is marked with its number from the list above. Look at their shapes the way a person would.)");
     // 인내심이 다 됐다는 단정이 아니라 조건이다. "볼 만큼 봤다" 고 하면 방문자가 그 자리에서 나갔다 — 진전이 있으면 이어 간다(10/14)
-    if (v.patienceSpent) lines.push("", "(Your patience is running low. Unless what is in front of you is getting you closer to what you came for, this is about where you would give up.)");
+    // 리서치 참여자는 과제를 하러 왔다 — 둘러보다 지치는 인내심 표시는 맞지 않는다
+    if (v.patienceSpent && !rec.study) lines.push("", "(Your patience is running low. Unless what is in front of you is getting you closer to what you came for, this is about where you would give up.)");
     return lines.join("\n");
   }
 
+  /**
+   * 리서치 위젯이 지금 무엇을 보여 주나. 다음 과제로 넘기기와 올리는 동안 기다리기는 여기서 한다 — 참여자가 늘 그냥 하는 것이다.
+   * @returns { card } 과제 질문·시간 초과 창(방문자가 answer_card 로 답한다) · { panel, skip, note } 과제 중 · { note } 끝남 · null
+   */
+  async studyLook(rec) {
+    const st = rec.study;
+    const page = rec.page;
+    rec.studyPending = null;
+    if (st.over) {
+      // 끝난 뒤 설문이 늦게 열리면(올린 뒤 서버가 알려 준다) 그때 한 번 말한다
+      if (st.surveyAt && !st.surveyTold) {
+        st.surveyTold = true;
+        return { note: "(The study has opened its short closing questionnaire for you — the page below. Fill it in as yourself; when you are done, you can leave.)" };
+      }
+      return null;
+    }
+    let s = null;
+    for (let i = 0; i < 6; i++) {
+      // 끝난 뒤 설문 페이지에도 #eb-plugin 이 있다(10/30 실험실) — 위젯을 읽지 않는다
+      s = study.isSurveyUrl(page.url()) ? null : await study.readStudy(page);
+      if (!s) break;
+      if (s.state === "next") {
+        await sleep(1200 + Math.random() * 1800);
+        await study.press(page, "next").catch(() => {});
+        await study.waitState(page, ["testing", "survey", "submit", "done"], 15000);
+        continue;
+      }
+      if (s.state === "submit" || s.state === "loading") {
+        await study.waitState(page, ["done", "complete", "testing", "survey", "next", "idle", "invite"], 120000);
+        continue;
+      }
+      break;
+    }
+    if (s && s.state === "survey" && s.question) {
+      rec.studyPending = { kind: "question", q: s.question, task: st.lastTask };
+      return { card: renderStudyQuestion(s.question, st.lastTask) };
+    }
+    if (s && s.state === "timeout" && s.timeout) {
+      rec.studyPending = { kind: "timeout", t: s.timeout, task: st.lastTask };
+      return { card: renderStudyTimeout(s.timeout, st.lastTask) };
+    }
+    if (s && s.state === "testing" && s.task) {
+      const key = `${s.task.progress}|${s.task.title}`;
+      let note = null;
+      if (st.lastTaskKey !== key) {
+        if (st.lastTaskKey) note = "(The study panel has moved on to a new task.)";
+        st.tasks.push({ title: s.task.title, progress: s.task.progress, at: Date.now() - rec.startedAt });
+      }
+      st.lastTaskKey = key;
+      st.lastTask = s.task.title;
+      return { panel: renderStudyPanel(s.task), skip: s.task.skip, note };
+    }
+    // 과제가 다 끝났다. 끝난 뒤 설문이 있으면 SDK 가 새 탭으로 열고, 그 탭은 이 탭으로 옮겨 온다(open 의 새 탭 처리)
+    if (st.tasks.length && (!s || !STUDY_ACTIVE.has(s.state))) {
+      st.over = true;
+      st.overAt = Date.now() - rec.startedAt;
+      if (!st.surveyAt) await sleep(4000);
+      if (st.surveyAt) {
+        st.surveyTold = true;
+        if (page.__ebPendingNav) await page.__ebPendingNav;
+        return { note: "(The study's tasks are done, and it opened a short closing questionnaire for you — the page below. Fill it in as yourself; when you are done, you can leave.)" };
+      }
+      return { note: "(The study's tasks are done — the panel thanked you. There is nothing more you have to do for it; carry on as you would, or leave.)" };
+    }
+    return null;
+  }
+
+  /** 과제 질문·시간 초과 창에 답한다. 참여하기로 한 사람이라 닫지 않는다 — 비워 두고 넘기는 건 된다(필수가 아니면) */
+  async studyAnswer(rec, decision) {
+    const p = rec.studyPending;
+    const st = rec.study;
+    const page = rec.page;
+    // 읽고 정하는 시간
+    await sleep(1200 + Math.random() * 2500);
+    let said;
+    if (p.kind === "timeout") {
+      const skip = decision.action === "choose" && decision.choiceIndex === 1;
+      await study.press(page, skip ? "timeoutSkip" : "keepGoing").catch(() => {});
+      if (skip) st.skipped.push(p.task);
+      said = skip ? `You chose to skip the task "${p.task}".` : "You chose to keep trying.";
+    } else {
+      const q = p.q;
+      const ans = decision.action === "choose" ? { index: decision.choiceIndex } : decision.action === "other" ? { text: decision.otherText } : {};
+      if (ans.index !== undefined && !(ans.index >= 0 && ans.index < q.options.length)) return ["That option number is not on the question.", "", await this.screen(rec)].join("\n");
+      const err = await study.answerQuestion(page, q, ans).catch((e) => `it did not go through (${String(e.message).split("\n")[0]})`);
+      if (err) return [`You could not send that: ${err}.`, "", await this.screen(rec)].join("\n");
+      const answer = ans.index !== undefined ? q.options[ans.index] : ans.text || null;
+      st.answers.push({ task: p.task, question: q.title, answer, why: decision.why });
+      said = answer ? `You answered: ${answer}` : "You left it blank and went on.";
+    }
+    rec.studyPending = null;
+    rec.visit.history.push(`The study asked "${p.kind === "timeout" ? "is this task difficult?" : p.q.title}" — ${said}`);
+    // 질문이 가로챈 조작은 일어나지 않았다 — 질문이 다 끝나 페이지로 돌아갈 때 한 번 말한다
+    if (rec.cutOff) {
+      const next = await study.readStudy(page);
+      if (!next || (next.state !== "survey" && next.state !== "timeout")) {
+        said += " What you were about to do on the page before the study's question appeared did not happen — do it again if you still want to.";
+        rec.cutOff = false;
+      }
+    }
+    await sleep(1500);
+    return [said, "", await this.screen(rec)].join("\n");
+  }
+
   /** 마지막 화면에 붙일 아이콘 그림. 한 번 가져가면 지운다(다음 화면은 새로 만든다) */
   takePicture(id) {
     const pic = this.pictures.get(id) || null;
@@ -447,8 +630,17 @@ class Hub {
   async act(id, decision) {
     const rec = this.get(id);
     const v = rec.visit;
+    // 리서치 질문이 페이지를 덮고 있다 — 먼저 답해야 한다
+    if (rec.studyPending) return ["The study's question is still open on top of the page — answer it with answer_card first.", "", await this.screen(rec)].join("\n");
     rec.lastAction = decision.action;
     const r = await v.act(decision);
+    // 패널의 건너뛰기를 눌렀다 — 그 과제를 건너뛴 것으로 남긴다
+    if (r && r.study === "skip" && !r.skipped && rec.study) rec.study.skipped.push(rec.study.lastTask);
+    if (r.interrupted && r.study) {
+      rec.cutOff = true;
+      return ["Before you could do that, the study asked you something.", "", await this.screen(rec)].join("\n");
+    }
+    if (r.studyCut) rec.cutOff = true;
     if (r.interrupted) {
       rec.cutOff = true;
       return ["Before you could do that, a survey card appeared.", "", await this.screen(rec)].join("\n");
@@ -489,6 +681,7 @@ class Hub {
   /** 카드에 답하거나 닫는다 */
   async answer(id, decision) {
     const rec = this.get(id);
+    if (rec.studyPending) return this.studyAnswer(rec, decision);
     const v = rec.visit;
     const c = await v.answer(decision);
     let done = c.result === "close" ? "You closed the card." : `You answered: ${c.answer}`;
@@ -521,6 +714,19 @@ class Hub {
       ms: Date.now() - rec.startedAt,
       sdkReady: rec.visit ? !!rec.visit.sdk?.ready : null,
       ...(rec.account ? { account: rec.account } : {}),
+      // 리서치 참여 — 어느 과제까지 갔고, 무엇을 건너뛰고, 과제 질문에 무엇을 답했나. 참여 기록 자체는 SDK 가 서버에 올린다
+      ...(rec.study
+        ? {
+            study: {
+              research: rec.study.research,
+              tasks: rec.study.tasks,
+              skipped: rec.study.skipped,
+              answers: rec.study.answers,
+              finished: rec.study.over,
+              questionnaire: !!rec.study.surveyAt,
+            },
+          }
+        : {}),
       // 도구가 하지 못한 것 — 고객도 자기 기록에서 볼 수 있게 종류만 남긴다(HTML·화면은 서버로만)
       ...(rec.visit && rec.visit.diag && rec.visit.diag.length ? { diag: rec.visit.diag.map(({ kind, action, shape, detail }) => ({ kind, action, shape, detail })) } : {}),
       ...extra,
@@ -780,6 +986,51 @@ function describeAccounts(accs, loginOpen) {
   return L.join("\n");
 }
 
+/** 과제 중인 리서치 패널 */
+function renderStudyPanel(task) {
+  return [
+    "## The study panel (in the corner of the screen)",
+    `${task.progress ? `${task.progress} — ` : ""}${task.title}`,
+    ...(task.about ? [task.about] : []),
+    ...(task.timeLeft ? [`Time left: ${task.timeLeft}`] : []),
+  ].join("\n");
+}
+
+/** 과제 질문(실패 이유 포함). 참여하기로 한 사람이라 답한다 */
+function renderStudyQuestion(q, task) {
+  const L = [
+    "## The study is asking you a question",
+    `This is part of the study you agreed to take part in${task ? ` (it comes after the task "${task}")` : ""}. It covers the page until you answer.`,
+    "",
+    ...(q.label ? [q.label] : []),
+    `Question: ${q.title}`,
+    ...(q.sub ? [q.sub] : []),
+  ];
+  if (q.kind === "choice") L.push("Options:", ...q.options.map((o, i) => `[${i}] ${o}`), ...(q.other ? ["There is also a box to type something else."] : []));
+  else if (q.kind === "scale") L.push(`A scale — pick one:${q.scaleLabels && q.scaleLabels.length ? ` (${q.scaleLabels.join(" … ")})` : ""}`, ...q.options.map((o, i) => `[${i}] ${o}`));
+  else if (q.kind === "yesno") L.push("Options:", ...q.options.map((o, i) => `[${i}] ${o}`));
+  else L.push(q.multiline ? "A box to write your answer in." : "A one-line box to type your answer in.");
+  L.push(
+    "",
+    "Answer as yourself with answer_card: bothered true, then choose an option (choice_index) or write your own words (action other, other_text) the way this person writes. Close only if you would leave it blank — that works only when the question does not require an answer.",
+  );
+  return L.join("\n");
+}
+
+/** 과제에 시간이 오래 걸리면 패널이 묻는다 */
+function renderStudyTimeout(t, task) {
+  return [
+    "## The study panel is asking you",
+    `You have been on the task${task ? ` "${task}"` : ""} for a while.`,
+    ...(t.text ? [t.text] : []),
+    "Options:",
+    `[0] ${t.keepGoing} — keep trying this task`,
+    `[1] ${t.skip} — give up on this task`,
+    "",
+    "Decide as yourself with answer_card: bothered true, then choose 0 or 1.",
+  ].join("\n");
+}
+
 function renderCard(card) {
   return [
     "## A survey card appeared on the screen",
@@ -792,6 +1043,17 @@ function renderCard(card) {
   ].join("\n");
 }
 
+/** 리서치 참여 한 줄 — 어디까지 갔나 */
+function studyLine(s) {
+  if (s.failed) return `Research: could not join — ${s.failed}`;
+  const reached = s.tasks.map((t) => `"${t.title}"`).join(" → ") || "no task";
+  const skipped = s.skipped.length ? ` · skipped ${s.skipped.map((t) => `"${t}"`).join(", ")}` : "";
+  const end = s.finished ? (s.questionnaire ? " · finished the tasks, closing questionnaire opened" : " · finished the tasks") : " · left before the end";
+  // 과제 질문의 답 — 보고에 쓴다(끝난 뒤 설문의 답은 그 페이지에서 쓴 것이라 걸음에 남는다)
+  const answers = s.answers.map((a) => `  - "${a.question}" → ${a.answer == null ? "(left blank)" : `"${String(a.answer).slice(0, 300)}"`}`);
+  return [`Research: tasks ${reached}${skipped} · ${s.answers.length} question(s) answered${end}`, ...answers].join("\n");
+}
+
 /** 방문 한 줄 요약 — 메인 에이전트가 모아서 사용자에게 보여준다 */
 function summarize(row) {
   const last = row.steps[row.steps.length - 1];
@@ -800,6 +1062,7 @@ function summarize(row) {
     `${row.person} (${row.device}) · ${row.entry?.how ?? "?"} → ${row.entry?.path ?? "/"} · ${row.steps.length} steps · ${Math.round(row.ms / 1000)}s`,
     row.pages?.length ? `Pages: ${row.pages.join(" → ")}` : "",
     card,
+    row.study ? studyLine(row.study) : "",
     last ? `Last: ${last.action} — ${last.why}` : row.blocked ? "Stopped at a block page" : "",
   ]
     .filter(Boolean)

package/mcp/server.js

@@ -117,9 +117,9 @@ server.registerTool(
   }),
 );
 
-/** 사람 한 줄: 기기 · 유입 → 착지 · 회원 · [기능] — 목적 */
+/** 사람 한 줄: 기기 · 유입 → 착지 · 회원 · [기능] · 리서치 — 목적 */
 const personLine = (p) =>
-  `${p.device} · ${p.arrival}${p.landing ? ` → ${p.landing}` : ""}${p.member ? " · member" : ""}${p.feature ? ` · [${p.feature}]` : ""} — ${p.goal}`;
+  `${p.device} · ${p.arrival}${p.landing ? ` → ${p.landing}` : ""}${p.member ? " · member" : ""}${p.feature ? ` · [${p.feature}]` : ""}${p.research ? ` · takes part in research ${p.research}` : ""} — ${p.goal}`;
 
 /** 사람들이 어느 기능에 몰려 있나 — 다음 판에 빈 곳을 채우라고 보여 준다 */
 function coverageLine(people) {
@@ -181,9 +181,13 @@ server.registerTool(
       site: z.string().url().describe("Site origin the visits go to"),
       site_about: z.string().describe("One or two English sentences on what the site is, as a visitor would understand it"),
       people: z.array(PERSON).min(1).max(50),
+      research: z
+        .string()
+        .optional()
+        .describe("Only when the run takes part in a research (the research command's research id): everyone saved in this call takes part in it"),
     },
   },
-  wrap(async ({ site, site_about, people }) => {
+  wrap(async ({ site, site_about, people, research }) => {
     const doc = ws.loadPeople();
     doc.site = new URL(site).origin;
     doc.siteAbout = site_about;
@@ -198,7 +202,8 @@ server.registerTool(
         return undefined;
       }
     };
-    const ids = peopleRules.withIds(doc.people, people.map((p) => ({ ...p, landing: landingOf(p.landing), createdAt: at, usedAt: null })));
+    const rid = (research || "").trim() || undefined;
+    const ids = peopleRules.withIds(doc.people, people.map((p) => ({ ...p, landing: landingOf(p.landing), research: rid, createdAt: at, usedAt: null })));
     for (const p of ids.incoming) p.traits = persona.coerceTraits(p.traits, peopleRules.personKey(p)).traits;
     doc.people = [...ids.existing, ...ids.incoming];
     ws.savePeople(doc);
@@ -923,8 +928,12 @@ const COMMANDS = {
       url: z.string().optional(),
       count: z.string().optional().describe('How many people (default 5), or "unlimited" to keep going until you stop it'),
       focus: z.string().optional().describe("Only people who come for this part of the site, e.g. calendar, or comments and sharing"),
+      research: z
+        .string()
+        .optional()
+        .describe("A research id from the dashboard: the people take part in that research — its tasks and questions — instead of exploring freely"),
     },
-    body: ({ url, count, focus }) => {
+    body: ({ url, count, focus, research }) => {
       const plan = researchPlan(count);
       run = { total: plan.total, since: Date.now() };
       // 사람 만드는 규칙은 우리 AI 로 만들 때와 같은 원본(people.md)에서 가져온다 — 두 벌로 두지 않는다.
@@ -938,7 +947,13 @@ const COMMANDS = {
           .replace(/^#/gm, "###");
       // focus 가 있으면 그 기능에 올 사람만 — 바뀌는 단계만 따로 적은 글을 앞에 붙인다. 방문자는 모른다
       const f = (focus || "").trim();
-      const focusPart = f ? doc("focus.md").replaceAll("{{focus}}", f).trim() + "\n\n" : "";
+      // 리서치에 참여시키는 판이면 그 리서치가 방문을 정한다 — focus 는 쓰지 않는다
+      const rid = (research || "").trim();
+      const focusPart = rid
+        ? doc("study.md").replaceAll("{{research}}", rid).trim() + "\n\n"
+        : f
+          ? doc("focus.md").replaceAll("{{focus}}", f).trim() + "\n\n"
+          : "";
       return doc("research.md")
         .replace("{{focus}}\n", focusPart)
         .replace("{{url}}", url || "(ask the user)")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.9",
+  "version": "0.2.10-next.1",
   "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/card.js

@@ -132,6 +132,8 @@ async function readCard(page) {
       const q = card.querySelector(".eb-ip-question");
       return {
         visible: card.classList.contains("eb-ip-visible"),
+        // 리서치 초대(수락 단추가 있다). 리서치에 참여 중인 방문은 이걸 질문 카드로 다루지 않는다(study.js 가 받는다)
+        invite: !!card.querySelector(".eb-ip-accept"),
         question: q ? q.textContent.trim() : "",
         choices: Array.from(card.querySelectorAll(".eb-ip-opt:not(.eb-ip-other):not(.eb-ip-decline)")).map((b) => b.textContent.trim()),
       };
@@ -188,7 +190,7 @@ async function answerCard(page, action) {
  * siteOrigin·key: 위조 대비 비밀값(`KEY_HEADER`). key 를 안 주면 환경변수 `USERCASE_AGENT_KEY`.
  * 비밀값이 있으면 siteOrigin 이 반드시 있어야 한다 — 그 origin 에만 보낸다.
  */
-async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true, persona = null, siteOrigin = null, key } = {}) {
+async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true, persona = null, research = null, siteOrigin = null, key } = {}) {
   /**
    * **HTTP 층에서도 밝힌다.** 아래 `window.Earningbirds.agent` 는 페이지 JS 안이라 우리 SDK 만 읽는다.
    * 고객의 WAF·CDN·분석 도구는 페이지 앞에 앉아 헤더만 보므로 그것만으로는 우릴 알아볼 수 없다.
@@ -203,7 +205,7 @@ async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true,
   // 비밀값은 고객이 정했을 때만. 정했는데 siteOrigin 을 안 주면 sendKey 가 멈춘다 — 새는 것보다 낫다
   await sendKey(ctx, siteOrigin, agentKey(key));
   await ctx.addInitScript(
-    ({ name, debugCards: dbg, hideDevOverlay: hide, persona: who }) => {
+    ({ name, debugCards: dbg, hideDevOverlay: hide, persona: who, research: rid }) => {
       if (dbg) {
         try {
           localStorage.setItem("Usercase_ip_debug", "1");
@@ -216,6 +218,8 @@ async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true,
         window.Usercase.agent = name;
         // 이 방문이 누구였는지. 닫고 나가도 남아야 해서 노출 때 같이 간다
         if (who) window.Usercase.agentPersona = who;
+        // 참여하러 온 리서치. SDK 가 도착하자마자 그 리서치의 초대를 조건 없이 띄운다(agent 가 있을 때만 믿는다)
+        if (rid) window.Usercase.agentResearch = rid;
       } catch (e) {}
       if (hide) {
         try {
@@ -234,7 +238,7 @@ async function markAgent(ctx, agent, { debugCards = true, hideDevOverlay = true,
         } catch (e) {}
       }
     },
-    { name: agent, debugCards, hideDevOverlay, persona },
+    { name: agent, debugCards, hideDevOverlay, persona, research },
   );
 }