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

package/mcp/hub.js

@@ -0,0 +1,760 @@
+"use strict";
+/**
+ * MCP 서버 안에서 브라우저와 진행 중인 방문들을 쥔다.
+ *
+ * 판단은 고객의 AI 도구가 한다 — 가상 사용자 한 명 = 서브에이전트 하나가 이 도구들을 한 걸음씩 부른다.
+ * 여기는 **몸**만 한다: 브라우저 열기(open.js), 방어선(guard.js), 사람 손(Visit), 차단 알아보기(blocked.js).
+ * 서브에이전트가 무엇을 시키든 이 선은 코드가 지킨다.
+ *
+ * 서브에이전트 여럿이 한 서버를 같이 쓴다 — 브라우저 하나에 방문마다 컨텍스트 하나.
+ */
+const fs = require("fs");
+const playwright = require("playwright");
+const persona = require("../src/persona/persona.js");
+const { personKey } = require("../src/persona/people.js");
+const entry = require("../src/run/entry.js");
+const { Visit, renderScreen, renderPerson } = require("../src/run/visit.js");
+const { createGuard } = require("../src/browser/guard.js");
+const policyMod = require("../src/browser/policy.js");
+const { loadRobots } = require("../src/browser/robots.js");
+const { launchBrowser, openVisit } = require("../src/browser/open.js");
+const { createBlockWatch, describeBlock } = require("../src/browser/blocked.js");
+const { waitForSdk, agentKey, KEY_ENV, KEY_HEADER, AGENT_HEADER, uaWith } = require("../src/browser/card.js");
+const ws = require("./workspace.js");
+const signin = require("../src/browser/signin.js");
+const { openRealChrome } = require("../src/browser/real-chrome.js");
+const report = require("./report.js");
+
+/**
+ * 가상 사용자 표시 이름. 서버가 이 이름으로 가상 사용자 답을 진짜 답과 갈라 센다
+ * (earningbirds-server insightFindingService.SYNTHETIC_AGENTS). 자유 탐방이라 qa-explore 와 같은 부류다.
+ */
+const AGENT = "qa-explore";
+/** 동시에 열어 둘 방문 수. 같은 사이트를 한꺼번에 두드리면 쓰로틀링에 걸린다(9/21 사람인) */
+const MAX_OPEN = 5;
+/** 서브에이전트가 죽으면 방문이 열린 채 남는다. 이만큼 조용하면 닫는다 */
+const IDLE_MS = 10 * 60 * 1000;
+
+/**
+ * 쓰기를 허용할 경로(정규식, 쉼표로). 로그인 뒤 화면은 조회도 POST 로 하는 사이트가 많다(GraphQL 등).
+ * 기본은 다 막는다 — 고객이 경로를 지정해 연다(PLAN.md "로그인")
+ */
+const ALLOW_WRITE_PATHS = (process.env.USERCASE_ALLOW_WRITE_PATHS || "").split(",").map((x) => x.trim()).filter(Boolean);
+
+/**
+ * 고객이 정한 금지 구역. `USERCASE_POLICY` 에 JSON 파일 경로(browser/policy.js 설명 참고).
+ * 없으면 기본값 — 가입·로그인·결제·글쓰기처럼 사이트에 흔적을 남기는 조작을 막는다.
+ * 쓰기를 보낼지는 사용자가 고른다(set_writes → .usercase/settings.json). 고르면 그때부터 여는 방문에 걸린다
+ */
+const POLICY_FILE = process.env.USERCASE_POLICY || null;
+const policyNow = () => policyMod.load(POLICY_FILE, { writes: ws.loadSettings().writes });
+
+/**
+ * 로컬 SDK 를 심어 돌리나(우리 내부 검증 — 운영 SDK 에 아직 가상 사용자 표시가 없다, PLAN.md "전제").
+ * 고객은 안 쓴다. 사이트에 박힌 SDK 로 돈다.
+ */
+function injectFromEnv() {
+  const project = process.env.USERCASE_INJECT_PROJECT;
+  if (!project) return null;
+  return {
+    project,
+    sdkSrc: process.env.USERCASE_SDK_SRC || "http://localhost:4000/dist/eb-plugin-web.js",
+    serverOrigin: process.env.USERCASE_SERVER_ORIGIN || "http://localhost:5000",
+  };
+}
+
+class Hub {
+  constructor() {
+    this.inject = injectFromEnv();
+    this.headed = process.env.USERCASE_HEADED === "1";
+    this.visits = new Map();
+    this.sites = new Map(); // origin → { guard, blockWatch, links }
+    this.browserP = null;
+    this.seq = 0;
+    // 시작할 때 비밀값을 한 번 검사한다 — 잘못된 값이 방문 도중 조용히 넘어가지 않게
+    this.keySet = !!agentKey();
+    setInterval(() => this.sweep(), 60 * 1000).unref();
+  }
+
+  browser() {
+    if (!this.browserP) {
+      const localSdk = !!this.inject && /localhost|127\.0\.0\.1/.test(this.inject.sdkSrc);
+      this.browserP = launchBrowser(playwright, { headed: this.headed, localSdk }).catch((e) => {
+        this.browserP = null;
+        throw e;
+      });
+    }
+    return this.browserP;
+  }
+
+  site(url) {
+    const origin = new URL(url).origin;
+    if (!this.sites.has(origin)) {
+      // 사이트마다 하나 — **반복되는지**가 "막혔나" 판단의 핵심이라 방문을 넘어 센다
+      const s = { origin, blockWatch: createBlockWatch(), links: null, robots: null };
+      this.arm(s);
+      this.sites.set(origin, s);
+    }
+    return this.sites.get(origin);
+  }
+
+  /** 지금 고른 쓰기 설정으로 방어선을 건다. 고르기를 바꾸면 다시 건다 — 이미 연 방문은 그대로다 */
+  arm(s) {
+    s.policy = policyNow();
+    // robots 는 나중에 읽는다(네트워크). 함수로 넘겨 읽히는 대로 반영되게
+    s.guard = createGuard({ site: s.origin, inject: this.inject, allowWritePaths: ALLOW_WRITE_PATHS, policy: s.policy, robots: () => s.robots });
+  }
+
+  /** 사이트에 쓰는 것을 보낼지. 사용자가 고른다 */
+  setWrites(mode) {
+    const next = ws.saveSettings({ writes: mode });
+    for (const s of this.sites.values()) this.arm(s);
+    return next.writes === "send"
+      ? "Writes are now SENT: visitors can sign up, post, comment, save and like, and those really reach the site. Signed-in visitors act as the demo account — they may change its profile and settings, and later member visits on that account see the changes. Payments, deleting, wallet connections, sign-out and password changes stay blocked, and personal fields (email, phone) are still not typed into. Applies to visits opened from now on."
+      : "Writes are now NOT SENT: visitors may still press Post, Save or Follow, but anything a page tries to send is stopped, and the visitor is told it was not sent. Applies to visits opened from now on.";
+  }
+
+  /**
+   * 사이트가 적어 둔 robots.txt 를 한 번 읽는다. **방문 전에 불러야** 금지 경로로 안 간다.
+   * 우리가 그 사이트에 보내는 첫 요청이라 여기서부터 자기를 밝힌다(헤더·비밀값).
+   */
+  async ensureRobots(s) {
+    if (s.robots) return s.robots;
+    const key = agentKey();
+    s.robots = await loadRobots(s.origin, {
+      headers: { [AGENT_HEADER]: AGENT, "User-Agent": uaWith(AGENT, "Mozilla/5.0 (compatible)"), ...(key ? { [KEY_HEADER]: key } : {}) },
+    });
+    process.stderr.write(`${s.origin} ${s.robots.describe()}\n`);
+    return s.robots;
+  }
+
+  async context(s, opts = {}) {
+    return openVisit(await this.browser(), playwright.devices, { agent: AGENT, site: s.origin, guard: s.guard, ...opts });
+  }
+
+  /** 돌리기 전 점검. 한 번 열어 보고 SDK·차단·비밀값을 말한다 */
+  async checkSite(url) {
+    const s = this.site(url);
+    await this.ensureRobots(s);
+    const watch = createBlockWatch({ minNetErrors: 1 });
+    const ctx = await this.context(s, { debugCards: false });
+    const out = [];
+    try {
+      const page = await ctx.newPage();
+      watch.watch(page, s.origin);
+      let status = null;
+      try {
+        const res = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 45000 });
+        status = res ? res.status() : null;
+      } catch (e) {
+        const msg = String(e.message).split("\n")[0];
+        // 로컬 사이트가 안 켜져 있는 것이다. 차단으로 읽으면 방화벽 안내가 나간다(10/14 bluetags 3001 이 꺼져 있었다)
+        if (s.guard.local && /ERR_CONNECTION_REFUSED/.test(msg)) {
+          return `Nothing is running at ${s.origin}. Start the site's dev server (or check the port), then run check_site again.`;
+        }
+        // 본문 없는 5xx 는 goto 가 이 오류로 끝난다
+        if (/ERR_HTTP_RESPONSE_CODE_FAILURE/.test(msg)) status = "error";
+        else out.push(`Could not open the page: ${msg}`);
+      }
+      const title = await page.title().catch(() => "");
+      watch.notePage({ title, text: await page.evaluate(() => (document.body || {}).innerText || "").catch(() => ""), path: new URL(url).pathname });
+      const v = watch.verdict();
+      if (v) {
+        out.push(describeBlock(v, { keySet: this.keySet }));
+        out.push("", "→ Do not run visits while the site is blocking them. Make the change above first.");
+        return out.join("\n");
+      }
+      // 사이트가 오류를 낸다(10/15 bluetags 개발 서버가 방문 도중 500). 차단이 아니라 잠깐 죽은 것일 수 있다
+      if (status === "error" || status >= 500) {
+        return `The site is answering with an error (${status === "error" ? "an HTTP error with an empty page" : `HTTP ${status}`}) — it looks down right now. If it is a dev server, it may come back by itself in a minute or two; otherwise restart it. Then run check_site again.`;
+      }
+      const sdk = await waitForSdk(page, { timeoutMs: 15000 });
+      const info = await page.evaluate(() => ({ project: (window.Usercase || window.Earningbirds || {}).project || null })).catch(() => ({}));
+      out.push(`✓ Opened (HTTP ${status ?? "?"}) — "${title.slice(0, 80)}"`);
+      // 심어서 돌릴 때는 우리가 준 id 를 말한다. 페이지의 값은 SDK 가 객체를 갈아 끼운 뒤 사이트 스니펫이
+      // 운영 id 로 덮어써서 틀린다(SDK 는 시작할 때 한 번 읽어 기록은 제대로 간다 — guard.js injectSdk 참고)
+      if (sdk.ready) out.push(`✓ Usercase SDK is running — project ${this.inject ? `${this.inject.project} (local SDK injected)` : info.project ?? "?"}`);
+      else
+        out.push(
+          "⚠ The Usercase SDK is not running on this site. Visitors can still browse (and with an API key their visits still reach the dashboard), but no survey cards will appear.",
+          "  If you are in this site's repository, install it: call install_snippet and follow it.",
+        );
+      // 우리 서버 쪽 키 — 방문 기록을 대시보드로 올린다(방화벽 비밀값과 다른 것)
+      out.push(await report.describeKey(sdk.ready ? (this.inject ? this.inject.project : info.project) : null));
+      out.push(
+        this.keySet
+          ? `✓ Firewall secret is set — sent only to this site, in the X-Usercase-Key header`
+          : `· No firewall secret (${KEY_ENV}). Fine if the site has no firewall; if visits get blocked, see "Running on a production site" in the @usercase/mcp README`,
+      );
+      // 사용자가 창을 닫자마자 부르는 일이 많다. 닫힌 뒤에도 쿠키를 읽고 확인하는 데 수십 초가 걸린다 —
+      // 그 사이에 "아직 열려 있다" 고 하면 사용자는 닫았는데 왜 또 묻냐고 한다(10/14). 끝날 때까지 기다린다
+      await this.waitLogin();
+      const accs = this.loginOpen ? ws.accounts() : await this.verifyAccounts(s);
+      if (accs.length || this.loginOpen) out.push(describeAccounts(accs, this.loginOpen && (this.loginClosed() ? "saving" : "open")));
+      const g = s.guard.summary();
+      if (g) out.push(`· Safety guard on — analytics tools (GA, Hotjar, etc.) are blocked`);
+      out.push(
+        s.policy.writes === "send"
+          ? "· Writes: SENT — visitors really sign up, post, comment and save on this site (payments, deleting and sign-out stay blocked). Change with set_writes"
+          : "· Writes: not sent — visitors may press Post or Save, but nothing is written to the site. Ask the user before the first round whether to send them (set_writes)",
+      );
+      // 도구가 하지 못한 것(진단) — 사이트 글자·주소 없이 종류와 요소 생김새만 우리 서버로 간다
+      out.push(
+        require("../src/run/diag.js").enabled()
+          ? "· Diagnostics on — when a visitor cannot do something (a button cut off, covered, unreachable), the kind of failure and the element's shape (tag, icon, in a carousel …) go to Usercase to improve the tool. No text, addresses or input from the site. Turn off with USERCASE_DIAGNOSTICS=off"
+          : "· Diagnostics off (USERCASE_DIAGNOSTICS=off)",
+      );
+      // 지키는 선을 고객이 볼 수 있게. 막혔는데 왜인지 모르면 우리 도구 탓으로 읽힌다
+      out.push(`· ${s.robots.describe()} — disallowed paths are not visited`);
+      out.push(`· ${s.policy.describe().split("\n")[0]} (to change it, set ${"USERCASE_POLICY"} to a JSON file path)`);
+      // 방문자가 처음 보는 것. 메인 에이전트가 사람을 만들 때 코드보다 이걸 먼저 봐야 사이트를 제대로 안다
+      // (9/21 스모크: 코드에서 description 만 grep 하고 Web3 정보 사이트를 "카드 공유 서비스" 로 알았다)
+      const first = await page
+        .evaluate(() => {
+          const nav = [...document.querySelectorAll("nav a, header a, [role=navigation] a")]
+            .map((a) => (a.innerText || "").trim())
+            .filter(Boolean);
+          return { nav: [...new Set(nav)].slice(0, 20), text: (document.body.innerText || "").replace(/\n{2,}/g, "\n").slice(0, 1500) };
+        })
+        .catch(() => null);
+      if (first) {
+        out.push("", "## First screen (what a visitor sees on arrival)");
+        if (first.nav.length) out.push(`Menu: ${first.nav.join(" · ")}`);
+        out.push("```", first.text, "```");
+      }
+      // 착지 화면을 고를 실제 주소. 검색·링크로 온 사람은 이 중 목적에 맞는 곳으로 들어온다(save_people landing)
+      const links = await this.links(s).catch(() => []);
+      if (links.length) {
+        const groups = new Map();
+        for (const l of links) {
+          const shape = l.split(/[?#]/)[0].replace(/\/[0-9a-f]{12,}|\/\d+(?=\/|$)/gi, "/:id");
+          if (!groups.has(shape)) groups.set(shape, []);
+          groups.get(shape).push(l);
+        }
+        out.push("", "Pages linked from the front page (real paths for `landing`; the code's routes have more):");
+        const named = (l) => (links.text && links.text[l] ? `${l} "${links.text[l]}"` : l);
+        for (const [shape, ls] of groups) {
+          if (ls.length === 1 && ls[0] === shape) out.push(`- ${named(shape)}`);
+          else out.push(`- ${shape}`, ...ls.slice(0, 6).map((l) => `    ${named(l)}`), ...(ls.length > 6 ? [`    (+${ls.length - 6} more)`] : []));
+        }
+      }
+      return out.join("\n");
+    } finally {
+      await ctx.close().catch(() => {});
+    }
+  }
+
+  /** 사이트 안 링크. 검색·공유로 들어오는 사람이 떨어질 자리다. 사이트마다 한 번만 모은다 */
+  async links(s) {
+    if (s.links) return s.links;
+    const ctx = await this.context(s, { debugCards: false });
+    try {
+      const page = await ctx.newPage();
+      s.blockWatch.watch(page, s.origin);
+      s.links = await entry.collectLinks(page, s.origin).catch(() => []);
+    } finally {
+      await ctx.close().catch(() => {});
+    }
+    return s.links;
+  }
+
+  /** 가상 사용자 한 명의 방문을 연다. 그 사람이 누구인지와 첫 화면을 돌려준다 */
+  async open(who) {
+    const doc = ws.loadPeople();
+    if (!doc.site) throw new Error("people.json has no site. Create people with save_people first.");
+    const p = doc.people.find((x) => x.id === who);
+    if (!p) throw new Error(`"${who}" is not in people.json. People: ${doc.people.map((x) => x.id).join(", ")}`);
+    const open = [...this.visits.values()].filter((v) => !v.closed).length;
+    if (open >= MAX_OPEN) throw new Error(`At most ${MAX_OPEN} visits can run at once. Wait for one to finish before opening another.`);
+    const s = this.site(doc.site);
+    const blockedAlready = s.blockWatch.verdict();
+    if (blockedAlready) return { stop: true, text: describeBlock(blockedAlready, { keySet: this.keySet }) + "\n\n→ The site is blocking visitors, so the visit was not opened. Stop running visits and tell the user what is above." };
+
+    await this.ensureRobots(s);
+    const links = await this.links(s);
+    const traits = persona.coerceTraits(p.traits, personKey(p)).traits;
+    const rhythm = new persona.Rhythm({ traits, visits: 1, device: p.device, source: p.traits ? "given" : "seed", seed: persona.seedOf(personKey(p)) });
+    const shape = persona.drawShape(Math.random, traits, persona.familiarityOf(1));
+    // 회원이면 고객이 login 으로 저장한 세션으로 들어간다. 비번은 우리가 모른다
+    let storageState;
+    let account = null;
+    if (p.member) {
+      account = pickAccount(p);
+      storageState = account.path;
+    }
+    // 사이트 밖으로 가려던 주소. 방어선이 끊고 여기 적는다 — 방문자에게 "다른 사이트로 가는 링크" 로 알린다
+    const offsite = [];
+    // 사이트에 쓰려다 끊긴 요청. 방문자에게 "보내지 않았다" 로 알린다 — 모르면 "저장이 안 된다" 가 사이트 문제로 기록된다
+    const notSent = [];
+    // 로컬 사이트가 바깥 서버에 닿으려다 끊긴 것(host). 방문자에게 "이 시험 실행에서는 거기 안 닿는다" 로 알린다
+    const external = [];
+    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" },
+    });
+    const page = await ctx.newPage();
+    s.blockWatch.watch(page, s.origin);
+    // 새 탭으로 여는 링크. 방문은 한 탭에서 하므로 닫는다 — 사이트 밖이면 방어선이 이미 적어 두었다
+    // 버튼이 스크립트로 여는 탭은 링크 주소가 없다 — 탭이 가려던 주소를 보고 적는다
+    ctx.on("page", (pop) => {
+      if (pop === page) return;
+      let noted = false;
+      const note = (u) => {
+        // http(s) 만 본다. 방어선이 끊은 탭은 크롬 오류 화면(chrome-error://chromewebdata)이 되는데,
+        // 그걸 갈 곳으로 적으면 "chromewebdata 라는 다른 사이트" 로 안내됐다(10/14 실험실 p22)
+        if (noted || !/^https?:/i.test(u || "")) return;
+        noted = true;
+        let same = false;
+        try {
+          same = new URL(u).origin === s.origin;
+        } catch {}
+        if (!same) return void offsite.push(u);
+        // 같은 사이트를 새 탭으로 여는 링크. 사람은 열린 탭에서 이어 본다 — 닫기만 하면 "눌러도 안 열린다" 가 된다
+        // (10/14 0.1.9 bluetags 프로젝트 카드 "See more" 가 target=_blank). 탭을 하나로 두려고 보던 탭을 그 주소로 옮긴다
+        pop.close().catch(() => {});
+        // 조작 뒤 기다림(settle)이 이 이동을 기다리게 걸어 둔다. 안 그러면 느린 화면에서 기다림이 먼저 끝나
+        // 방문자는 "안 열렸다" 를 보고, 다시 누르면 그새 넘어가 "없어졌다" 가 된다(10/14 실험실 p3)
+        const going = page
+          .goto(u, { waitUntil: "domcontentloaded", referer: page.url(), timeout: 30000 })
+          .catch(() => {})
+          .finally(() => {
+            if (page.__ebPendingNav === going) page.__ebPendingNav = null;
+          });
+        page.__ebPendingNav = going;
+      };
+      pop.on("request", (req) => {
+        if (req.isNavigationRequest()) note(req.url());
+      });
+      note(pop.url());
+      // 새 탭 소식은 늦게, 주소가 빈 채로 올 때가 있다 — 주소가 생길 때까지 3초 본다. 그래도 없으면 닫는다
+      (async () => {
+        for (let i = 0; i < 30 && !noted && !pop.isClosed(); i++) {
+          await new Promise((r) => setTimeout(r, 100));
+          note(pop.url());
+        }
+        pop.close().catch(() => {});
+      })();
+    });
+    const id = `v${++this.seq}`;
+    // 정해 둔 착지 화면이 금지 경로(robots.txt·정책)면 쓰지 않는다 — 무작위 상세나 홈으로 들어온다
+    let landingOff = null;
+    if (p.landing) {
+      const pathOnly = p.landing.split(/[?#]/)[0];
+      landingOff = (s.robots && s.robots.blocked(pathOnly) && "robots.txt") || s.policy.pathReason(pathOnly);
+    }
+    const how = entry.chooseEntry(landingOff ? { ...p, landing: undefined } : p, links);
+    if (landingOff) process.stderr.write(`${p.id}: landing ${p.landing} is off limits (${landingOff}) — entering elsewhere\n`);
+    const rec = { id, person: p, site: s, ctx, page, how, startedAt: Date.now(), touched: Date.now(), closed: false, visit: null };
+    this.visits.set(id, rec);
+
+    await page.goto(s.origin + how.path, { waitUntil: "domcontentloaded", referer: how.referer || undefined, timeout: 60000 }).catch(() => {});
+    // 화면이 보여도 사이트 코드가 아직 안 붙었으면 버튼이 안 먹는다. 바로 상세·달력으로 들어오면 첫 클릭이 그렇게 사라졌다
+    // (10/15 실험실 p14, 달력 Month). 사람도 다 뜰 때까지 잠깐 본다 — 조용해질 때까지 최대 10초
+    await page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => {});
+    // 차단 페이지는 정상 응답으로 와서 goto 가 성공한다. 화면을 보고 가린다 — 막혔으면 걷지 않는다
+    const blocked = s.blockWatch.notePage({
+      title: await page.title().catch(() => ""),
+      text: await page.evaluate(() => (document.body || {}).innerText || "").catch(() => ""),
+      path: how.path,
+    });
+    if (blocked) {
+      await this.finish(rec, { blocked: true });
+      const v = s.blockWatch.verdict();
+      return { stop: true, text: (v ? describeBlock(v, { keySet: this.keySet }) : "The site showed a block page.") + "\n\n→ Blocked. Stop running visits and tell the user what is above." };
+    }
+    // 회원인데 화면에 로그인 링크가 있다 — 세션이 풀렸다. 이 계정으로는 더 걷지 않는다(비회원 화면이 회원 기록이 된다)
+    // 확인 때 "로그인하면 링크가 사라진다" 를 본 사이트만 이걸로 판단한다
+    if (account && account.status === "signed_in") {
+      const marks = await signin.signInMarks(page);
+      if (marks.length) {
+        ws.setAccountStatus(account.account, "expired", `a member visit still saw ${marks.slice(0, 2).join(", ")}`);
+        this.visits.delete(id);
+        rec.closed = true;
+        await ctx.close().catch(() => {});
+        throw new Error(
+          `Account ${account.account}'s sign-in has expired, so ${p.id} was not visited (it would have been a signed-out visit recorded as a member). Ask the user to sign in again with login (account: "${account.account}") — never ask for a password. Other members use the remaining accounts.`,
+        );
+      }
+    }
+    rec.account = account ? account.account : null;
+    rec.visit = new Visit(page, p, { rhythm, shape, policy: s.policy, offsite, notSent, external });
+    const sdk = await rec.visit.begin();
+    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 (!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") };
+  }
+
+  /** 지금 화면(또는 떠 있는 카드)을 에이전트가 읽을 글로 */
+  async screen(rec) {
+    const v = rec.visit;
+    const look = await v.look();
+    if (look.ended) return "This visit has ended.";
+    if (look.card) return renderCard(look.card);
+    const lines = [renderScreen(look)];
+    // 인내심이 다 됐다는 단정이 아니라 조건이다. "볼 만큼 봤다" 고 하면 방문자가 그 자리에서 나갔다 — 진전이 있으면 이어 간다(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.)");
+    return lines.join("\n");
+  }
+
+  get(id) {
+    const rec = this.visits.get(id);
+    if (!rec) throw new Error(`No visit ${id}`);
+    if (rec.closed) throw new Error(`Visit ${id} has already ended`);
+    rec.touched = Date.now();
+    return rec;
+  }
+
+  /** 한 걸음. 끝나면 기록하고 닫는다 */
+  async act(id, decision) {
+    const rec = this.get(id);
+    const v = rec.visit;
+    const r = await v.act(decision);
+    if (r.interrupted) return ["Before you could do that, a survey card appeared.", "", await this.screen(rec)].join("\n");
+    const said = [];
+    if (r.offsite) said.push(`That leads to another website (${r.offsite}). It did not open here — you are still on this site. If going there is what you would do, that means leaving this site.`);
+    if (r.skipped) said.push(`That did not happen: ${r.skipped}.`);
+    if (r.notSent) said.push("That would have sent something to the site (saving, posting or signing up). In this run nothing is sent to the site, so it was not saved. Whatever the screen shows next (an error, or no change) comes from that, not from the site — carry on as you would have if it had worked.");
+    if (r.external) said.push(`Part of this page needs another server (${r.external.join(", ")}), which this test run of the site on your computer does not reach. Whatever depends on it (live chat, sending, live prices) cannot finish here — that is the test setup, not the site. Carry on as you would have if it had worked.`);
+    if (r.heldEnter) said.push("The screen changed as you typed, so you did not press Enter — what you see is what typing alone did. If you would press Enter now, type the same text into that field again.");
+    if (r.fileWindow) said.push(r.fileWindow);
+    if (r.openedApp) said.push("That tried to open another app outside the browser (a share or app link). Nothing opened, and you are back on the page you were on.");
+    if (r.swiped) said.push("It was cut off at the edge, so you swiped that row sideways to bring it into view, then tapped it.");
+    // 개인정보 칸. 사이트가 막은 게 아니라 이 사람이 안 친 것이다 — 그렇게 알린다
+    if (r.personalField !== undefined) said.push(`You don't type personal details such as your email, phone number or real name into this site on this visit, so you left that field empty. Carry on as you would without filling it in — skip it, or go elsewhere.`);
+    if (r.closedOverlay) said.push("Something was open on top of the page; your click landed outside it and closed it, so it did not reach what you clicked.");
+    if (r.missed) said.push("Your click landed just outside it and nothing happened.");
+    if (r.typos) said.push(`(You made ${r.typos} typo(s) and fixed them.)`);
+    if (v.ended) {
+      if (v.pending) return [...said, "As you were leaving, a survey card appeared.", "", renderCard(v.pending)].join("\n");
+      const sum = await this.finish(rec);
+      return [...said, "You left the site. This visit is over.", "", sum].join("\n");
+    }
+    return [...said, ...(said.length ? [""] : []), await this.screen(rec)].join("\n");
+  }
+
+  /** 카드에 답하거나 닫는다 */
+  async answer(id, decision) {
+    const rec = this.get(id);
+    const v = rec.visit;
+    const c = await v.answer(decision);
+    const done = c.result === "close" ? "You closed the card." : `You answered: ${c.answer}`;
+    if (v.ended) {
+      const sum = await this.finish(rec);
+      return [done, "This visit is over.", "", sum].join("\n");
+    }
+    return [done, "", await this.screen(rec)].join("\n");
+  }
+
+  /** 방문을 닫고 기록을 남긴다. 사람 파일에 쓴 날을 적는다 */
+  async finish(rec, extra = {}) {
+    if (rec.closed) return "";
+    rec.closed = true;
+    const res = rec.visit ? rec.visit.result() : { steps: [], card: null, shape: null };
+    const row = {
+      at: new Date().toISOString(),
+      site: rec.site.origin,
+      person: rec.person.id,
+      personUid: rec.person.uid,
+      device: rec.person.device,
+      goal: rec.person.goal,
+      entry: rec.how,
+      steps: res.steps,
+      pages: [...new Set(res.steps.map((s) => s.path))],
+      card: res.card,
+      ms: Date.now() - rec.startedAt,
+      sdkReady: rec.visit ? !!rec.visit.sdk?.ready : null,
+      ...(rec.account ? { account: rec.account } : {}),
+      // 도구가 하지 못한 것 — 고객도 자기 기록에서 볼 수 있게 같이 남긴다(서버로 가는 것과 같은 내용)
+      ...(rec.visit && rec.visit.diag && rec.visit.diag.length ? { diag: rec.visit.diag } : {}),
+      ...extra,
+    };
+    ws.appendRun(row);
+    // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
+    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
+    // 도구가 하지 못한 것들 — 우리 쪽 진단으로(사이트 글자 없음). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
+    if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device).catch(() => 0);
+    const doc = ws.loadPeople();
+    const p = doc.people.find((x) => x.id === rec.person.id);
+    if (p) {
+      p.usedAt = row.at;
+      ws.savePeople(doc);
+    }
+    await new Promise((r) => setTimeout(r, 1500));
+    await rec.ctx.close().catch(() => {});
+    return [summarize(row), uploaded].filter(Boolean).join("\n");
+  }
+
+  /**
+   * 고객이 직접 로그인하게 브라우저를 띄운다. **비밀번호는 우리를 지나가지 않는다** — 로그인된 세션(쿠키)만 저장한다.
+   * 도구는 바로 돌아온다. 창이 열려 있는 동안 몇 초마다 세션을 저장하고, 창을 닫으면 끝난다.
+   *
+   * 방어선(guard)은 걸지 않는다 — 로그인 자체가 쓰기(POST)이고, 누르는 사람은 고객이다.
+   * 가상 사용자 표시(헤더·비밀값)는 붙인다 — 방화벽을 지나야 하고, 이 방문이 진짜 방문자로 세어지면 안 된다.
+   * 구글 등 일부 소셜 로그인은 자동화된 브라우저를 거절할 수 있다. 그때는 데모 계정의 아이디·비번 로그인을 쓰게 안내한다.
+   */
+  /**
+   * @param window     "chrome"(일반 크롬 — 구글·소셜 로그인이 된다) | "playwright"(닫기 전에 읽는다 — 브라우저를 닫으면 지워지는 쿠키도 남는다). 없으면 chrome 부터
+   * @param lifetimeH  코드로 본 세션 수명(시간). 알면 언제 끝나는지 보여 주고, 지나면 그 계정을 쓰지 않는다
+   */
+  /** 로그인 창이 닫혔나(닫혔어도 저장·확인 중이면 loginOpen 은 아직 true) */
+  loginClosed() {
+    if (!this.loginOpen) return true;
+    if (this.loginReal) return this.loginReal.closed();
+    return !!this.loginFinishing;
+  }
+
+  /** 로그인 창 마무리를 기다린다. 창이 열려 있으면 조금(방금 닫는 중일 수 있다), 닫혔으면 확인이 끝날 때까지 */
+  async waitLogin() {
+    const t0 = Date.now();
+    while (this.loginOpen && Date.now() - t0 < (this.loginClosed() ? 90000 : 15000)) await new Promise((r) => setTimeout(r, 500));
+  }
+
+  async login(url, account, { window: win = null, lifetimeH = null } = {}) {
+    if (this.loginOpen) return "A sign-in window is already open. Sign in, then close that window.";
+    ws.ensure();
+    account = account || ws.nextAccount();
+    if (!ws.ACCOUNT_NAME.test(account)) throw new Error(`Account name "${account}" — use letters, numbers, - or _ (e.g. a1, a2)`);
+    const file = ws.sessionPath(account);
+    const s = this.site(url);
+
+    // 먼저 PC 의 일반 크롬으로. 자동화 브라우저는 구글·소셜 로그인이 막힌다(10/14 bluetags Google)
+    // 일반 크롬은 창을 닫을 때 "브라우저를 닫으면 지워지는" 쿠키를 버린다. 그런 쿠키로 로그인하는 사이트는
+    // 크롬으로 해도 로그인 안 됨으로 나온다 — 그 계정은 다음부터 닫기 전에 읽는 Playwright 창으로 연다(10/14)
+    this.chromeDropped = this.chromeDropped || new Set();
+    const viaChrome = win !== "playwright" && process.env.USERCASE_LOGIN_BROWSER !== "playwright" && !this.chromeDropped.has(`${s.origin} ${account}`);
+    const extra = { ...(typeof lifetimeH === "number" && lifetimeH > 0 ? { lifetimeH } : {}) };
+    if (viaChrome) {
+      const real = await openRealChrome({
+        url: s.origin + "/",
+        origin: s.origin,
+        onSave: (state) => {
+          try {
+            fs.writeFileSync(file, JSON.stringify(state, null, 2));
+          } catch {}
+        },
+        onDone: async () => {
+          await this.verifyAccounts(s, [account]).catch(() => {});
+          const a = ws.accounts().find((x) => x.account === account);
+          ws.setAccountStatus(account, a ? a.status : "unchecked", a ? a.note : null, { ...extra, via: "chrome" });
+          if (a && a.status === "signed_out") {
+            this.chromeDropped.add(`${s.origin} ${account}`);
+            ws.setAccountStatus(
+              account,
+              "signed_out",
+              `${a.note}. This site may sign people in with a cookie that Chrome deletes when its window closes — the next login for this account opens a different window that keeps it (Google sign-in may not work there; use email and password)`,
+            );
+          }
+          this.loginReal = null;
+          this.loginOpen = false;
+        },
+      }).catch(() => null);
+      if (real) {
+        this.loginOpen = true;
+        this.loginReal = real;
+        return [
+          `A Chrome window for account "${account}" is open on the user's screen, on the site's first screen.`,
+          "1. Sign in there yourself with a **demo account**, the way you normally would — Google and other sign-in buttons work in this window. With a real account, the visitors' activity would mix into that account's history.",
+          `2. When you are signed in, close the window. Only this site's cookies are saved, as account "${account}" in .usercase/sessions/ — the password is never seen or stored, and the window uses a fresh, empty Chrome profile that is deleted afterwards.`,
+          "3. Then run check_site. It checks whether the sign-in really worked; if it did not, open login again for the same account. Never ask for the password.",
+        ].join("\n");
+      }
+    }
+
+    const browser = await launchBrowser(playwright, { headed: true, localSdk: !!this.inject && /localhost|127\.0\.0\.1/.test(this.inject.sdkSrc) });
+    const noGuard = { apply: async () => {}, local: false };
+    const ctx = await openVisit(browser, playwright.devices, { agent: AGENT, site: s.origin, guard: noGuard, debugCards: false });
+    const page = await ctx.newPage();
+    this.loginOpen = true;
+    this.loginBrowser = browser;
+    let saved = 0;
+    // ctx.storageState() 는 부를 때마다 빈 탭을 열었다 닫는다 — 3초마다 부르니 로그인 창이 깜빡였다(10/14).
+    // 쿠키는 탭 없이 읽고, localStorage 는 열려 있는 사이트 페이지에서 읽는다. 사이트 것만 있으면 된다
+    let siteStorage = null;
+    const save = async () => {
+      try {
+        const cookies = await ctx.cookies();
+        if (page.url().startsWith(s.origin)) {
+          siteStorage = await page.evaluate(() => Object.entries(localStorage).map(([name, value]) => ({ name, value }))).catch(() => siteStorage);
+        }
+        const state = { cookies, origins: siteStorage ? [{ origin: s.origin, localStorage: siteStorage }] : [] };
+        fs.writeFileSync(file, JSON.stringify(state, null, 2));
+        saved++;
+      } catch {}
+    };
+    // 창을 통째로 닫으면 컨텍스트가 먼저 사라져 마지막 저장을 못 할 수 있다. 열려 있는 동안 계속 저장한다
+    const timer = setInterval(save, 3000);
+    let finishing = false;
+    const done = async () => {
+      if (finishing) return;
+      finishing = true;
+      this.loginFinishing = true;
+      clearInterval(timer);
+      await save();
+      await browser.close().catch(() => {});
+      // 창을 닫았다고 로그인된 게 아니다. 세션을 넣은 화면과 안 넣은 화면을 비교해 둔다 — check_site 가 보여 준다
+      await this.verifyAccounts(s, [account]).catch(() => {});
+      const a = ws.accounts().find((x) => x.account === account);
+      if (a) {
+        // 두 창 다 해 봤는데 안 됐다 — 이 사이트는 이 도구로 로그인한 방문을 못 할 수 있다. 사용자가 알아야 한다
+        const both = this.chromeDropped.has(`${s.origin} ${account}`);
+        const note =
+          a.status === "signed_out" && both
+            ? `${a.note}. Both sign-in windows were tried. If the user did sign in, signed-in visits are not possible on this site with this tool — tell the user plainly, and run newcomers only`
+            : a.note;
+        ws.setAccountStatus(account, a.status, note, { ...extra, via: "playwright" });
+      }
+      this.loginOpen = false;
+      this.loginFinishing = false;
+    };
+    page.on("close", done);
+    // 창을 통째로 닫아도 같은 마무리 — 마지막 저장은 못 해도 열려 있는 동안 저장한 것으로 확인한다
+    browser.on("disconnected", done);
+    // 10분 지나면 닫는다
+    setTimeout(done, 10 * 60 * 1000).unref();
+    // 사이트 첫 화면을 먼저 연다. 로그인 뒤 "뒤로" 돌려보내는 사이트가 있다 — 빈 탭에서 바로 열면 about:blank 로 간다(10/14 bluetags router.back)
+    (async () => {
+      if (new URL(url).pathname !== "/") await page.goto(s.origin + "/", { waitUntil: "domcontentloaded" }).catch(() => {});
+      await page.goto(url, { waitUntil: "domcontentloaded" }).catch(() => {});
+    })();
+    return [
+      `A sign-in window for account "${account}" is open on the user's screen.`,
+      "1. Sign in there yourself with a **demo account**. With a real account, the visitors' activity would mix into that account's history.",
+      `2. When you are signed in, close the window. Only the session (cookies) is saved, as account "${account}" in .usercase/sessions/ — the password is never seen or stored.`,
+      "3. Then run check_site. It checks whether the sign-in really worked; if it did not, open login again for the same account. Never ask for the password.",
+      "If Google sign-in or similar refuses with 'this browser may not be secure', use an email and password sign-in instead.",
+    ].join("\n");
+  }
+  /**
+   * 계정마다 로그인이 됐나 본다. 세션 없는 화면 한 번 + 계정마다 한 번.
+   * @param only  이 계정들만(없으면 전부)
+   */
+  async verifyAccounts(s, only = null) {
+    const list = ws.accounts().filter((a) => !only || only.includes(a.account));
+    if (!list.length) return ws.accounts();
+    const url = s.origin + "/";
+    const anonCtx = await this.context(s, { debugCards: false });
+    const anon = await signin.marksAt(anonCtx, url).finally(() => anonCtx.close().catch(() => {}));
+    for (const a of list) {
+      const ctx = await this.context(s, { debugCards: false, storageState: a.path }).catch(() => null);
+      if (!ctx) {
+        ws.setAccountStatus(a.account, "signed_out", "the saved session could not be read");
+        continue;
+      }
+      const marks = await signin.marksAt(ctx, url).finally(() => ctx.close().catch(() => {}));
+      const j = signin.judge(anon, marks);
+      ws.setAccountStatus(a.account, j.status, j.note);
+    }
+    return ws.accounts();
+  }
+
+
+  /** 버려진 방문 닫기 */
+  sweep() {
+    for (const rec of this.visits.values()) {
+      if (!rec.closed && Date.now() - rec.touched > IDLE_MS) this.finish(rec, { abandoned: true }).catch(() => {});
+    }
+  }
+
+  /** 이 서버가 돌린 방문과 막은 것 */
+  status() {
+    const lines = [];
+    for (const s of this.sites.values()) {
+      const g = s.guard.summary();
+      const v = s.blockWatch.verdict();
+      lines.push(`${s.origin}${v ? " — ⚠ blocked" : ""}`);
+      if (g) lines.push(`  Blocked requests: writes to the site ${g.writes.join(", ") || "none"} · analytics ${g.trackers} · production SDK ${g.production}`);
+    }
+    const open = [...this.visits.values()].filter((r) => !r.closed).map((r) => `${r.id} ${r.person.id} (${r.visit?.steps.length ?? 0} steps)`);
+    if (open.length) lines.push(`In progress: ${open.join(", ")}`);
+    return lines.join("\n");
+  }
+
+  async close() {
+    for (const rec of this.visits.values()) if (!rec.closed) await this.finish(rec, { abandoned: true }).catch(() => {});
+    if (this.browserP) await (await this.browserP).close().catch(() => {});
+    if (this.loginBrowser) await this.loginBrowser.close().catch(() => {});
+    if (this.loginReal) await this.loginReal.close().catch(() => {});
+  }
+}
+
+/**
+ * 회원을 어느 계정에 앉히나. 사람마다 늘 같은 계정 — 다시 와도 같은 사람이다.
+ * people.json 에 account 를 적으면 그 계정. 확인해서 로그인 안 된 계정에는 앉히지 않는다
+ */
+function pickAccount(p) {
+  const all = ws.accounts();
+  if (!all.length) throw new Error(`${p.id} is a member but no demo account is signed in. Run login first so the user can sign in.`);
+  const usable = all.filter((a) => a.status === "signed_in" || a.status === "unknown" || a.status === "unchecked");
+  if (p.account) {
+    const a = all.find((x) => x.account === p.account);
+    if (!a) throw new Error(`${p.id} uses account "${p.account}", which has no sign-in. Run login with account "${p.account}".`);
+    if (!usable.includes(a)) throw new Error(`${p.id} uses account "${p.account}", which is not signed in (${a.status}). Ask the user to sign in again with login (account: "${p.account}").`);
+    return a;
+  }
+  if (!usable.length) {
+    throw new Error(
+      `${p.id} is a member but none of the accounts is signed in (${all.map((a) => `${a.account}: ${a.status}`).join(", ")}). Ask the user to sign in again with login. If signing in cannot work on this site, tell the user that signed-in visits are not possible here and make the remaining people newcomers.`,
+    );
+  }
+  return usable[persona.seedOf(personKey(p)) % usable.length];
+}
+
+const STATUS_TEXT = {
+  signed_in: "signed in",
+  signed_out: "NOT signed in",
+  expired: "sign-in EXPIRED",
+  unknown: "saved, but could not confirm it is signed in",
+  unchecked: "saved, not checked yet",
+};
+
+/** check_site 에 보일 계정 목록. 안 된 계정은 무엇을 하라고 같이 적는다 */
+function describeAccounts(accs, loginOpen) {
+  const L = [accs.length ? `· Demo accounts (${accs.length}) — members are spread across the signed-in ones:` : "· Demo accounts: none saved yet"];
+  for (const a of accs) {
+    const left = a.expiresAt && a.status === "signed_in" ? Math.max(0, (Date.parse(a.expiresAt) - Date.now()) / 36e5) : null;
+    const when = left === null ? `saved ${a.ageH}h ago` : left < 1 ? `about ${Math.max(1, Math.round(left * 60))} min left` : `about ${Math.round(left)}h left`;
+    let line = `  - ${a.account}: ${STATUS_TEXT[a.status] || a.status}${a.note ? ` — ${a.note}` : ""} (${when})`;
+    if (a.status === "signed_out" || a.status === "expired") line += ` → ask the user to sign in again with login (account: "${a.account}")`;
+    if (a.status === "unknown") line += " → ask the user whether they were signed in when they closed the window";
+    L.push(line);
+  }
+  if (loginOpen === "saving") L.push("  (the sign-in window is closed; the sign-in is still being saved and checked — run check_site again in a moment, without asking the user anything)");
+  else if (loginOpen) L.push("  (the sign-in window is still open on the user's screen — run check_site again after the user closes it)");
+  return L.join("\n");
+}
+
+function renderCard(card) {
+  return [
+    "## A survey card appeared on the screen",
+    `Question: ${card.question}`,
+    ...(card.choices.length
+      ? ["Options:", ...card.choices.map((c, i) => `[${i}] ${c}`), "There is also a box to type your own answer, and a close button."]
+      : ["No options — only a box to type your own words, and a close button."]),
+    "",
+    "Decide as yourself with answer_card: first whether you would bother at all, then what.",
+  ].join("\n");
+}
+
+/** 방문 한 줄 요약 — 메인 에이전트가 모아서 사용자에게 보여준다 */
+function summarize(row) {
+  const last = row.steps[row.steps.length - 1];
+  const card = row.card ? `Card "${row.card.question}" → ${row.card.result === "close" ? "closed" : row.card.answer}` : "No card";
+  return [
+    `${row.person} (${row.device}) · ${row.entry?.how ?? "?"} → ${row.entry?.path ?? "/"} · ${row.steps.length} steps · ${Math.round(row.ms / 1000)}s`,
+    card,
+    last ? `Last: ${last.action} — ${last.why}` : row.blocked ? "Stopped at a block page" : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+module.exports = { Hub, AGENT, MAX_OPEN, summarize };