@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/mcp/path.js

@@ -0,0 +1,394 @@
+"use strict";
+/**
+ * 과제의 정상 경로를 기록한다 — 대시보드 리서치 과제의 "바로 성공 / 돌아서 성공" 기준.
+ *
+ * 가상 사용자 방문과 다르다. 여기서 걷는 건 **메인 에이전트**다: 코드를 읽어 만든 사람이 의도한 길을 알고,
+ * 그 길만 빠르게 걷는다(사람 손·머뭇거림 없음). 걸음마다 SDK 의 경로 기록 화면(earningbirds-core scripts/path-setting.ts)이
+ * 남기는 것과 같은 것을 남긴다: 페이지 = 경로 + 화면, 누른 것 = XPath + 요소 화면.
+ * 그다음 새 브라우저로 같은 길을 다시 걸어(check) 요소가 그대로 찾아지는지 보고, 사용자가 승인하면 올린다(save).
+ *
+ * SDK 가 참여자의 클릭을 경로 단계에 맞추는 규칙(core/SequenceTracker.ts):
+ *  - XPath 로 찾은 요소가 클릭된 요소를 **품으면** 맞다 → 버튼 안쪽 글자를 눌러도 맞게, 버튼·링크 자체를 기록한다
+ *  - class 목록은 **하나라도** 맞으면(`.a,.b`) 맞다 → 흔한 class(flex 등)를 넣으면 아무 데나 눌러도 맞는다.
+ *    그래서 class·id 는 그 요소 하나만 가리킬 때만 남긴다
+ *  - 호스트는 비운다(모든 호스트). 로컬 개발 서버에서 걸어도 운영에서 맞아야 한다
+ */
+const fs = require("fs");
+const path = require("path");
+const ws = require("./workspace.js");
+const report = require("./report.js");
+const { listControls, visibleText, handleAt, clickBlocked } = require("../src/browser/page.js");
+const { renderScreen, settle, watchNet } = require("../src/run/visit.js");
+
+/** 화면을 찍을 때 우리 것(질문 카드·위젯)은 가린다 — 참여자 화면에는 없는 것이다 */
+const HIDE_OWN = "#eb-insight,#eb-plugin,#eb-plugin-entry,#usercase_container,#usercase-overlay,#earningbirds_container,#earningbirds-overlay{visibility:hidden !important}";
+/** 기록할 요소 — 누른 자리에서 가장 가까운 누를 수 있는 것 */
+const PICK_SEL = 'a[href],button,[role="button"],[role="link"],[role="tab"],[role="menuitem"],summary,label,input,select,textarea';
+const MAX_STEPS = 30;
+
+/** SDK 와 같은 경로 패턴 — `:id` 는 한 조각, 뒤에 /·?·# 허용 */
+const patternOf = (p) => new RegExp(`^${p.replace(/:\w+/g, "([^\\/]+)")}/?(\\?.*|#.*)?$`);
+const pathOnly = (u) => {
+  const p = new URL(u).pathname;
+  return p.length > 1 ? p.replace(/\/+$/, "") : "/";
+};
+
+/**
+ * 요소 하나를 SDK 가 맞출 수 있는 모양으로. 브라우저 안에서 돈다.
+ * XPath 는 SDK main/utils.ts getElementXPath 와 같은 방식(같은 이름 형제 사이 순번, svg 는 name())
+ */
+function describeInPage(n, pickSel) {
+  const pick = (n.closest && n.closest(pickSel)) || n;
+  const xp = (e) => {
+    const parts = [];
+    while (e && e.nodeType === 1) {
+      let idx = 0;
+      let has = false;
+      for (let s = e.previousSibling; s; s = s.previousSibling) if (s.nodeType === 1 && s.nodeName === e.nodeName) idx++;
+      for (let s = e.nextSibling; s; s = s.nextSibling)
+        if (s.nodeType === 1 && s.nodeName === e.nodeName) {
+          has = true;
+          break;
+        }
+      const tag = e.namespaceURI === "http://www.w3.org/2000/svg" ? '*[name()="svg"]' : e.nodeName.toLowerCase();
+      parts.unshift(tag + (has || idx > 0 ? `[${idx + 1}]` : ""));
+      e = e.parentNode;
+    }
+    return parts.length ? (parts[0].startsWith("//*") ? parts.join("/") : `/${parts.join("/")}`) : null;
+  };
+  const cls = Array.from(pick.classList || []).filter(Boolean);
+  let classes = [];
+  try {
+    const sel = cls.map((c) => "." + CSS.escape(c)).join(",");
+    if (sel && document.querySelectorAll(sel).length === 1) classes = cls;
+  } catch (e) {}
+  // SDK 는 id 를 이스케이프 없이 `#id` 로 쓴다 — 평범한 id 만(React useId 의 ":r1:" 같은 건 SDK 에서 오류가 난다)
+  const ids = pick.id && /^[A-Za-z][\w-]*$/.test(pick.id) && document.querySelectorAll("#" + pick.id).length === 1 ? [pick.id] : [];
+  const label = (pick.getAttribute("aria-label") || pick.innerText || pick.value || pick.getAttribute("title") || "").replace(/\s+/g, " ").trim().slice(0, 80);
+  return { xpath: xp(pick), classes, ids, label, tag: pick.tagName.toLowerCase() };
+}
+
+/** XPath 로 요소를 찾는다(SDK 처럼 첫 번째) */
+function byXPathInPage(xpath) {
+  try {
+    return document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 화면이 다 떴나. 조용해질 때까지(최대 10초) 보고, 그래도 글자가 하나도 없으면 30초까지 기다린다 —
+ * 개발 서버는 처음 여는 화면을 만드는 동안 빈 문서를 준다. 빈 화면을 단계로 찍으면 사용자에게 보여 줄 그림이 없다(10/15 실험실)
+ */
+async function ready(page) {
+  await page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => {});
+  await page.waitForFunction(() => document.body && document.body.innerText.trim().length > 0, null, { timeout: 30000 }).catch(() => {});
+  await page.waitForTimeout(300);
+}
+
+const sameLabel = (a, b) => {
+  const n = (s) => (s || "").replace(/\s+/g, " ").trim().toLowerCase();
+  return n(a) === n(b) || (n(a) && n(b) && (n(a).includes(n(b)) || n(b).includes(n(a))));
+};
+
+class PathRecorder {
+  constructor(hub) {
+    this.hub = hub;
+    /** taskId → { research, task } — path_tasks 로 받아 둔다 */
+    this.known = new Map();
+    this.cur = null;
+  }
+
+  /** 리서치의 과제들 */
+  async tasks(researchId) {
+    const r = await report.getResearchTasks(researchId);
+    for (const t of r.tasks) this.known.set(String(t.taskId), { research: r.research, task: t });
+    const cond = (t) =>
+      t.condition === "url_entry" ? `done on reaching ${t.targetUrl || "(no page set)"}` : t.condition === "element_click" ? `done on clicking an element on ${t.xpathUrl || "?"}` : `done after ${t.timer}s`;
+    return [
+      `Research "${r.research.title}" (${r.research.status})${r.research.website ? ` — site ${r.research.website}` : ""}`,
+      r.research.purpose ? `Purpose: ${r.research.purpose}` : "",
+      "",
+      ...r.tasks.map((t) =>
+        [
+          `### Task ${t.taskId} — ${t.title}`,
+          `- what the participant is told: ${t.infoText || "(nothing)"}`,
+          `- success: ${cond(t)}`,
+          `- expected path: ${t.pathSteps ? `${t.pathSteps} steps recorded (recording again replaces them)` : "NONE — results cannot tell going straight from a detour"}`,
+        ].join("\n"),
+      ),
+    ]
+      .filter((x) => x !== "")
+      .join("\n");
+  }
+
+  async open(s, { device, account }) {
+    let storageState;
+    if (account) {
+      const a = ws.accounts().find((x) => x.account === account);
+      if (!a) throw new Error(`No signed-in demo account "${account}". Run login first, or leave account out.`);
+      storageState = a.path;
+    }
+    await this.hub.ensureRobots(s);
+    return this.hub.context(s, { device, storageState, debugCards: false });
+  }
+
+  /** 새로 기록을 시작한다. 같은 과제를 다시 하면 처음부터 */
+  async start({ task, url, device = "desktop", account = null }) {
+    const k = this.known.get(String(task));
+    if (!k) throw new Error(`Task ${task} is not known yet. Call path_tasks with the research id first.`);
+    const full = /^https?:\/\//i.test(url) ? url : new URL(url, k.research.website || undefined).toString();
+    await this.stop();
+    const s = this.hub.site(full);
+    const ctx = await this.open(s, { device, account });
+    const page = await ctx.newPage();
+    ws.ensure();
+    const dir = path.join(ws.DIR, "paths", String(task));
+    fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    this.cur = { taskId: String(task), title: k.task.title, s, ctx, page, net: watchNet(page), dir, startUrl: full, device, account, steps: [], actions: [], view: null, checked: null };
+    await page.goto(full, { waitUntil: "domcontentloaded", timeout: 90000 });
+    await ready(page);
+    await this.recordPage();
+    return this.screen(`Recording the expected path for task ${task} ("${k.task.title}"). Step 1 is this page.`);
+  }
+
+  need() {
+    if (!this.cur) throw new Error("No path is being recorded. Call path_start first.");
+    return this.cur;
+  }
+
+  async shot(file, handle = null) {
+    const c = this.cur;
+    const opts = { type: "jpeg", quality: 65, style: HIDE_OWN, timeout: 15000 };
+    try {
+      if (handle) return await handle.screenshot({ ...opts, path: file });
+    } catch {}
+    return c.page.screenshot({ ...opts, path: file });
+  }
+
+  /** 지금 페이지를 경로 단계로 — 바로 앞 페이지 단계와 같은 경로면 넘긴다 */
+  async recordPage() {
+    const c = this.cur;
+    const p = pathOnly(c.page.url());
+    const lastPage = [...c.steps].reverse().find((x) => x.type === "URL");
+    if (lastPage && lastPage.concrete === p) return null;
+    const file = path.join(c.dir, `${String(c.steps.length + 1).padStart(2, "0")}-page.jpg`);
+    await this.shot(file);
+    const step = { type: "URL", url: p, concrete: p, image: file };
+    c.steps.push(step);
+    c.checked = null;
+    return step;
+  }
+
+  async screen(head) {
+    const c = this.cur;
+    const view = await listControls(c.page);
+    c.view = view;
+    const text = await visibleText(c.page);
+    // 빈 화면을 단계로 남기면 사용자에게 보여 줄 그림이 비고, 다시 걸어도 같은 걸 못 찾는다
+    const empty = !text.trim() && !view.items.length;
+    const warn = empty
+      ? "⚠ The page shows nothing — it may still be loading or the site returned an error. Do not build the path on this: call path_start again (or open the page in a browser to see what is wrong)."
+      : "";
+    return [head, warn, "", this.stepsText(), "", renderScreen({ view, text })].filter((x, i) => i !== 1 || x).join("\n");
+  }
+
+  stepsText() {
+    const c = this.cur;
+    return [
+      `## Path so far (${c.steps.length} steps)`,
+      ...c.steps.map((s, i) => `${i + 1}. ${s.type === "URL" ? `page ${s.url}` : `${s.pressed === false ? "final click (not pressed)" : "click"} "${s.label || s.tag}" on ${s.url}${s.classes.length || s.ids.length ? "" : " (matched by position only)"}`}`),
+    ].join("\n");
+  }
+
+  /** 누른다 — 기본은 경로 단계로 남긴다. record=false 는 길에 끼지 않는 것(쿠키 배너 닫기 등) */
+  async click({ index, record = true, press = true }) {
+    const c = this.need();
+    if (c.steps.length >= MAX_STEPS) throw new Error(`A path has at most ${MAX_STEPS} steps.`);
+    const item = c.view && c.view.items[index];
+    const el = item ? await handleAt(c.page, index) : null;
+    if (!el) return this.screen(`[${index}] is not on the screen any more. Here is the current screen.`);
+    const blocked = press ? clickBlocked(item, { policy: c.s.policy }) : null;
+    if (blocked)
+      return this.screen(
+        `Not pressed — ${blocked}. If this is where the participant's task ends (e.g. the final "Pay" or "Submit" button), call path_click again with press=false: it is recorded as the final click without pressing it.`,
+      );
+    const pickH = await el.evaluateHandle((n, sel) => (n.closest && n.closest(sel)) || n, PICK_SEL);
+    const info = await el.evaluate(describeInPage, PICK_SEL);
+    if (!info.xpath) return this.screen(`Could not work out where [${index}] is in the page. Try another element.`);
+    const at = pathOnly(c.page.url());
+    let step = null;
+    if (record) {
+      const file = path.join(c.dir, `${String(c.steps.length + 1).padStart(2, "0")}-click.jpg`);
+      await pickH.asElement().scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
+      await this.shot(file, pickH.asElement());
+      step = { type: "XPATH", url: at, concrete: at, xpath: info.xpath, classes: info.classes, ids: info.ids, label: info.label, tag: info.tag, image: file, pressed: press };
+      c.steps.push(step);
+    }
+    c.actions.push({ do: "click", xpath: info.xpath, label: info.label, press, step: step ? c.steps.length - 1 : null });
+    c.checked = null;
+    if (!press) return this.screen(`Recorded "${info.label || info.tag}" as the final click, without pressing it. The path ends here — call path_check next.`);
+    const before = c.page.url();
+    try {
+      await pickH.asElement().click({ timeout: 10000 });
+    } catch (e) {
+      if (step) c.steps.pop();
+      c.actions.pop();
+      return this.screen(`Clicking "${info.label || info.tag}" failed (${String(e.message).split("\n")[0]}). Nothing was recorded.`);
+    }
+    await settle(c.page, before, c.net);
+    await ready(c.page);
+    const page = await this.recordPage();
+    // 다시 걸을 때 이 클릭 뒤에 닿아야 할 페이지(길에 끼지 않는 클릭이 페이지를 바꿨어도)
+    c.actions[c.actions.length - 1].pageStep = page ? c.steps.length - 1 : null;
+    return this.screen(`Clicked "${info.label || info.tag}"${record ? "" : " (not part of the path)"}.${page ? ` Now on ${page.url}.` : ""}`);
+  }
+
+  /** 칸에 친다 — 경로 단계는 아니지만 다시 걸을 때 똑같이 친다(검색어 등) */
+  async type({ index, text }) {
+    const c = this.need();
+    const el = c.view && c.view.items[index] ? await handleAt(c.page, index) : null;
+    if (!el) return this.screen(`[${index}] is not on the screen any more.`);
+    const info = await el.evaluate(describeInPage, "input,textarea,select,[contenteditable]");
+    await el.fill(text, { timeout: 10000 });
+    c.actions.push({ do: "type", xpath: info.xpath, text });
+    c.checked = null;
+    return this.screen(`Typed into "${info.label || info.tag}" (not a path step; it is repeated when the path is checked).`);
+  }
+
+  async scroll({ up = false }) {
+    const c = this.need();
+    await c.page.mouse.wheel(0, (up ? -1 : 1) * Math.round((c.view?.viewport || 800) * 0.8));
+    await c.page.waitForTimeout(400);
+    return this.screen(`Scrolled ${up ? "up" : "down"}.`);
+  }
+
+  /** 페이지 단계의 경로를 패턴으로(`/notice/123` → `/notice/:id`) — 참여자마다 다른 글을 열어도 맞게 */
+  async pattern({ step, url }) {
+    const c = this.need();
+    const s = c.steps[step - 1];
+    if (!s) throw new Error(`There is no step ${step}.`);
+    if (!url.startsWith("/")) throw new Error("The pattern must be a path starting with /");
+    if (!patternOf(url).test(s.concrete)) throw new Error(`"${url}" does not match the page that was recorded (${s.concrete}).`);
+    let n = 0;
+    for (const x of c.steps)
+      if (x.concrete === s.concrete) {
+        x.url = url;
+        n++;
+      }
+    c.checked = null;
+    return `${n} step(s) on ${s.concrete} now use ${url}.\n\n${this.stepsText()}`;
+  }
+
+  /** 새 브라우저로 같은 길을 다시 걷는다. 요소가 그대로 찾아지고 같은 페이지에 닿아야 통과 */
+  async check() {
+    const c = this.need();
+    if (!c.steps.length) throw new Error("Nothing recorded yet.");
+    const ctx = await this.open(c.s, { device: c.device, account: c.account });
+    const lines = [];
+    let ok = true;
+    try {
+      const page = await ctx.newPage();
+      const net = watchNet(page);
+      await page.goto(c.startUrl, { waitUntil: "domcontentloaded", timeout: 90000 });
+      await ready(page);
+      const pageCheck = (k) => {
+        const s = c.steps[k];
+        const here = pathOnly(page.url());
+        const hit = patternOf(s.url).test(here);
+        lines.push(`${hit ? "✓" : "✗"} ${k + 1}. page ${s.url}${hit ? "" : ` — landed on ${here} instead`}`);
+        return hit;
+      };
+      ok = pageCheck(0);
+      for (const a of c.actions) {
+        if (!ok) break;
+        const h = (await page.evaluateHandle(byXPathInPage, a.xpath)).asElement();
+        const visible = h ? await h.isVisible().catch(() => false) : false;
+        const label = h ? await h.evaluate((n) => (n.getAttribute("aria-label") || n.innerText || n.value || n.getAttribute("title") || "").replace(/\s+/g, " ").trim().slice(0, 80)) : "";
+        const no = a.step !== null ? `${a.step + 1}. ` : "   ";
+        if (!h || !visible) {
+          lines.push(`✗ ${no}${a.do} "${a.label || a.text || ""}" — ${h ? "found but not visible" : "not found at its recorded position"} (${a.xpath})`);
+          ok = false;
+          break;
+        }
+        if (a.do === "type") {
+          await h.fill(a.text, { timeout: 10000 });
+          lines.push(`✓    typed "${a.text}"`);
+          continue;
+        }
+        if (!sameLabel(label, a.label)) {
+          // 길에 끼지 않는 클릭(목록에서 하나 고르기)은 다른 항목이어도 된다 — 뒤의 페이지 패턴이 맞는지 본다
+          if (a.step === null) lines.push(`·    picked "${label}" this time (recorded "${a.label}") — fine for a pick that is not a step`);
+          else {
+            lines.push(`✗ ${no}click "${a.label}" — that position now holds "${label}" (the page differs between visits, e.g. list order)`);
+            ok = false;
+            break;
+          }
+        }
+        if (!a.press) {
+          lines.push(`✓ ${no}final click "${a.label}" is there (not pressed)`);
+          continue;
+        }
+        const before = page.url();
+        try {
+          await h.click({ timeout: 10000 });
+        } catch (e) {
+          lines.push(`✗ ${no}click "${a.label}" — ${String(e.message).split("\n")[0]}`);
+          ok = false;
+          break;
+        }
+        await settle(page, before, net);
+        await ready(page);
+        lines.push(`✓ ${no}click "${a.step === null ? label : a.label}"`);
+        // 기록할 때 이 클릭 뒤에 새 페이지에 닿았으면 다시 걸어도 거기 닿아야 한다
+        if (a.pageStep != null) ok = pageCheck(a.pageStep);
+      }
+    } finally {
+      await ctx.close().catch(() => {});
+    }
+    c.checked = ok ? this.signature() : null;
+    return [
+      ok ? "PASSED — the path walks the same way in a fresh browser." : "FAILED — fix the path (record it again, or use path_pattern for pages whose address changes) before saving.",
+      ...lines,
+      "",
+      "Screenshots to show the user (in order):",
+      ...c.steps.map((s, i) => `${i + 1}. ${s.image}`),
+    ].join("\n");
+  }
+
+  signature() {
+    return JSON.stringify(this.cur.steps.map((s) => [s.type, s.url, s.xpath || ""]).concat(this.cur.actions.map((a) => [a.do, a.xpath, a.text || ""])));
+  }
+
+  /** 올린다. 다시 걸어 통과한 그대로여야 한다 */
+  async save({ success = "keep" }) {
+    const c = this.need();
+    if (!c.checked || c.checked !== this.signature()) throw new Error("Run path_check first — only a path that passed, unchanged since, can be saved.");
+    const body = {
+      steps: c.steps.map((s) => ({ type: s.type, url: s.url, xpath: s.xpath || "", classes: s.classes || [], ids: s.ids || [], image: fs.readFileSync(s.image).toString("base64") })),
+    };
+    if (success === "page") {
+      const last = [...c.steps].reverse().find((s) => s.type === "URL");
+      body.success = { condition: "url_entry", targetUrl: last.url };
+    } else if (success === "click") {
+      const last = [...c.steps].reverse().find((s) => s.type === "XPATH");
+      if (!last) throw new Error("There is no recorded click to use as the success condition.");
+      body.success = { condition: "element_click", xpath: last.xpath, xpathUrl: last.url, classes: last.classes, ids: last.ids };
+    }
+    const r = await report.savePath(c.taskId, body);
+    const done = `Saved the expected path for task ${c.taskId} ("${c.title}"): ${r.steps} steps${r.success ? `, success condition set to ${r.success === "url_entry" ? `reaching ${body.success.targetUrl}` : `clicking "${[...c.steps].reverse().find((s) => s.type === "XPATH").label}"`}` : ""}. The dashboard's task results now separate going straight from detours.`;
+    await this.stop();
+    return done;
+  }
+
+  async stop() {
+    if (!this.cur) return;
+    this.cur.net.stop();
+    await this.cur.ctx.close().catch(() => {});
+    this.cur = null;
+  }
+}
+
+module.exports = { PathRecorder, patternOf };

package/mcp/report.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * 방문 기록을 어닝버드 서버로 올린다 — 대시보드 "방문"·"가상 사용자 실행" 화면이 이걸 읽는다.
+ *
+ * 프로젝트 API 키(`USERCASE_API_KEY`, 대시보드 설정 → 연동 → API 키)가 있을 때만 보낸다. 키가 프로젝트를 정한다.
+ * 키가 없으면 기록은 지금처럼 고객 컴퓨터(.usercase/runs)에만 남는다.
+ * 못 보낸 기록은 .usercase/outbox.jsonl 에 두었다가 다음 방문이 끝날 때 다시 보낸다(서버는 같은 id 를 한 번만 받는다).
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const ws = require("./workspace.js");
+
+const KEY_ENV = "USERCASE_API_KEY";
+const URL_ENV = "USERCASE_API_URL";
+const DEFAULT_API = "https://app.usercase.io/koa";
+const KEY_RE = /^eb_sk_[A-Za-z0-9]{32}$/;
+const OUTBOX = path.join(ws.DIR, "outbox.jsonl");
+
+const apiKey = () => (process.env[KEY_ENV] || "").trim();
+const apiBase = () => (process.env[URL_ENV] || DEFAULT_API).replace(/\/$/, "");
+
+/** 이 MCP 세션 하나 = 실행 하나. 대시보드가 실행별로 묶는다 */
+const RUN_REF = `run_${new Date().toISOString().slice(0, 10)}_${crypto.randomBytes(6).toString("hex")}`;
+
+async function call(method, route, body, timeoutMs = 15000) {
+  const res = await fetch(`${apiBase()}${route}`, {
+    method,
+    headers: { Authorization: `Bearer ${apiKey()}`, "Content-Type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text();
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {}
+  if (!res.ok) throw Object.assign(new Error((json && json.error) || `HTTP ${res.status}`), { status: res.status });
+  return json;
+}
+
+/** 키 상태 한 줄 — check_site 가 보여 준다. sdkProject 가 있으면 키의 프로젝트와 맞는지 본다 */
+async function describeKey(sdkProject) {
+  const key = apiKey();
+  if (!key) return `· No API key (${KEY_ENV}). Visits stay on this computer and are not sent to the dashboard. Create one in the dashboard: Settings → Integrations → API keys`;
+  if (!KEY_RE.test(key)) return `⚠ ${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`;
+  try {
+    const me = await call("GET", "/agent/me");
+    if (sdkProject && me.projectId !== sdkProject)
+      return `⚠ The API key belongs to the "${me.title}" project, but the SDK on this site sends to another project (${sdkProject}). Visits and card answers would land in different projects. Use the key for the right project`;
+    return `✓ API key — visits are sent to the "${me.title}" project`;
+  } catch (e) {
+    if (e.status === 401) return `⚠ The API key is wrong or revoked. Create a new one in the dashboard`;
+    return `⚠ Could not reach the Usercase server (${e.message}). Visits can still run; records will be sent later`;
+  }
+}
+
+/** 키의 프로젝트와 그 설치 스크립트(서버가 대시보드 설치 화면과 같은 글을 준다) — install_snippet 이 쓴다 */
+async function getInstall() {
+  const key = apiKey();
+  if (!key) throw new Error(`No API key (${KEY_ENV}). Create one in the dashboard (Settings → Integrations → API keys), then add this MCP server again with -e ${KEY_ENV}=<key>`);
+  if (!KEY_RE.test(key)) throw new Error(`${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`);
+  try {
+    const me = await call("GET", "/agent/me");
+    if (!me.snippet) throw new Error("The Usercase server did not return a script. It may be an older server version");
+    return me;
+  } catch (e) {
+    if (e.status === 401) throw new Error("The API key is wrong or revoked. Create a new one in the dashboard");
+    throw e;
+  }
+}
+
+function readOutbox() {
+  if (!fs.existsSync(OUTBOX)) return [];
+  return fs
+    .readFileSync(OUTBOX, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+function writeOutbox(items) {
+  ws.ensure();
+  if (!items.length) {
+    if (fs.existsSync(OUTBOX)) fs.unlinkSync(OUTBOX);
+    return;
+  }
+  fs.writeFileSync(OUTBOX, items.map((x) => JSON.stringify(x)).join("\n") + "\n");
+}
+
+/** 방문 하나를 서버로 보낼 모양 — 사람의 이름은 없다(번호만) */
+function payload(row, person, startedAt) {
+  return {
+    id: crypto.randomUUID(),
+    run: RUN_REF,
+    tool: "claude-code",
+    site: row.site,
+    person: person.id,
+    personUid: person.uid,
+    persona: {
+      background: person.background,
+      goal: person.goal,
+      moment: person.moment,
+      attention: person.attention,
+      surveyHabit: person.surveyHabit,
+      writing: person.writing,
+      arrival: person.arrival,
+      member: !!person.member,
+      traits: person.traits,
+    },
+    device: person.device,
+    entry: row.entry,
+    steps: row.steps,
+    card: row.card,
+    ms: row.ms,
+    startedAt: new Date(startedAt).toISOString(),
+  };
+}
+
+/**
+ * 방문 하나를 보내고, 전에 못 보낸 것도 같이 보낸다. 실패해도 방문은 막지 않는다 — 결과 한 줄만 돌려준다.
+ * @returns 요약에 붙일 한 줄, 키가 없으면 null
+ */
+async function sendVisit(row, person, startedAt) {
+  if (!KEY_RE.test(apiKey())) return null;
+  const queue = [...readOutbox(), payload(row, person, startedAt)];
+  const left = [];
+  let sent = 0;
+  let lastErr = null;
+  for (const item of queue) {
+    try {
+      await call("POST", "/agent/visits", item);
+      sent++;
+    } catch (e) {
+      lastErr = e;
+      // 키가 틀렸으면 다시 보내도 소용없다 — 그래도 버리지 않고 남겨 둔다(키를 고치면 다음에 간다)
+      left.push(item);
+    }
+  }
+  writeOutbox(left);
+  if (!left.length) return `· Sent to the dashboard${sent > 1 ? ` (${sent} including earlier ones)` : ""}`;
+  return `⚠ Could not upload to the dashboard (${lastErr?.status === 401 ? "API key rejected" : lastErr?.message}) — ${left.length} kept in ${OUTBOX}, will retry next time`;
+}
+
+/**
+ * 도구가 하지 못한 것들(진단)을 보낸다 — 우리 도구를 고치려고. 사이트 글자·주소는 없다(src/run/diag.js).
+ * 키가 있고 꺼 두지 않았을 때만. 실패해도 조용히 넘어간다 — 방문과는 상관없다
+ */
+async function sendDiagnostics(events, device) {
+  const diag = require("../src/run/diag.js");
+  if (!events || !events.length || !diag.enabled() || !KEY_RE.test(apiKey())) return 0;
+  try {
+    const out = await call("POST", "/agent/diagnostics", { run: RUN_REF, version: require("../package.json").version, device, events: events.slice(0, 100) });
+    return (out && out.saved) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** 키가 있어야 하는 호출 — 없거나 틀렸으면 사용자에게 할 말로 바꿔 던진다 */
+async function keyed(method, route, body, timeoutMs) {
+  const key = apiKey();
+  if (!key) throw new Error(`No API key (${KEY_ENV}). Create one in the dashboard (Settings → Integrations → API keys), then add this MCP server again with -e ${KEY_ENV}=<key>`);
+  if (!KEY_RE.test(key)) throw new Error(`${KEY_ENV} does not look right (38 characters starting with eb_sk_). Copy it again from the dashboard`);
+  try {
+    return await call(method, route, body, timeoutMs);
+  } catch (e) {
+    if (e.status === 401) throw new Error("The API key is wrong or revoked. Create a new one in the dashboard");
+    if (e.status === 404) throw new Error(`${e.message}. Check the id — it must belong to the project of this API key`);
+    throw e;
+  }
+}
+
+/** 리서치의 과제들과 지금 경로가 있는지 — 경로 설정(path)이 쓴다 */
+const getResearchTasks = (researchId) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/tasks`);
+
+/** 과제의 정상 경로를 통째로 바꾼다. 화면을 올리느라 오래 걸릴 수 있다 */
+const savePath = (taskId, body) => keyed("PUT", `/agent/tasks/${encodeURIComponent(taskId)}/path`, body, 90000);
+
+/** 질문 만들기(question) — 최근 방문을 읽어야 해서 조금 걸린다 */
+const getQuestionContext = () => keyed("GET", "/agent/questions/context", null, 60000);
+const checkQuestion = (condition) => keyed("POST", "/agent/questions/check", { condition }, 60000);
+const saveQuestion = (body) => keyed("POST", "/agent/questions", body, 60000);
+/** 대시보드 주소. API 주소에서 /koa 를 뗀다 */
+const dashboardUrl = (p) => apiBase().replace(/\/koa$/, "") + p;
+
+module.exports = {
+  KEY_ENV,
+  URL_ENV,
+  RUN_REF,
+  describeKey,
+  getInstall,
+  sendVisit,
+  sendDiagnostics,
+  getResearchTasks,
+  savePath,
+  getQuestionContext,
+  checkQuestion,
+  saveQuestion,
+  dashboardUrl,
+};