agentlas 1.0.29 → 1.0.36

package/engine/automation/launchd.cjs

@@ -0,0 +1,131 @@
+"use strict";
+/*
+ * automation/launchd — 앱/창이 꺼져 있어도 자동화를 돌리는 macOS 영속성 (2026-08-06).
+ *
+ * 배경(오너: "터미널인데 모든 기능이 다 돼야"): 터미널 automation daemon 은 포그라운드
+ * setInterval 이라 셸 창을 닫으면 멈춘다 — "데스크탑 없이 자동화가 발동"이 실제론 안 됐다.
+ * 데스크탑 electron/launchd/agent.ts 와 같은 방식으로 ~/Library/LaunchAgents 에 plist 를 써서
+ * launchctl 로 로드한다. plist 는 coarse StartInterval(기본 300s)마다 `agentlas automation tick`
+ * (1회 due 스윕 후 종료)을 poke 한다. DB 가 스케줄 권위이고 plist 는 poke 만 하므로 자동화별
+ * plist 동기화가 필요 없다 — 데스크탑과 정확히 같은 계약.
+ *
+ * ★Label 은 데스크탑("ai.agentlas.automations")과 다르게 둔다("ai.agentlas.cli.automations").
+ *   둘 다 설치돼 있어도 공유 DB 의 lease(claimDue)가 이중 실행을 막으므로 공존은 안전하고,
+ *   서로의 plist 를 install/uninstall 로 덮지 않게 하려는 것.
+ *
+ * macOS 전용(launchd). 다른 OS 는 supported:false 로 정직하게 알린다(자동화는 포그라운드
+ * `automation daemon` 으로만 — 조용히 안 되는 척하지 않는다).
+ */
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { userDataDir } = require("../core/paths.cjs");
+
+const LABEL = "ai.agentlas.cli.automations";
+
+function isSupported() { return process.platform === "darwin"; }
+function plistPath() { return path.join(os.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`); }
+function domainTarget() { return `gui/${os.userInfo().uid}`; }
+
+/** launchd 가 poke 할 CLI 진입점(절대경로). 전역 설치본이든 체크아웃이든 이 파일 기준으로 해석. */
+function cliEntry() { return path.resolve(__dirname, "..", "..", "bin", "agentlas.cjs"); }
+
+function logPath() {
+  const dir = path.join(userDataDir(), "logs");
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* best-effort */ }
+  return path.join(dir, "launchd-automations.log");
+}
+
+function plistXml(intervalSec = 300) {
+  const node = process.execPath;
+  const entry = cliEntry();
+  const log = logPath();
+  const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    `    <string>${esc(node)}</string>`,
+    `    <string>${esc(entry)}</string>`,
+    "    <string>automation</string>",
+    "    <string>tick</string>",
+    "  </array>",
+    "  <key>StartInterval</key>",
+    `  <integer>${Math.max(30, Math.floor(intervalSec))}</integer>`,
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>ProcessType</key>",
+    "  <string>Background</string>",
+    "  <key>LowPriorityIO</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${esc(log)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${esc(log)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+/** launchctl 실행 — throw 하지 않고 {code, stderr} 반환(상태 함수가 판정). */
+function launchctl(args) {
+  const res = spawnSync("launchctl", args, { encoding: "utf8" });
+  return { code: res.status ?? -1, stderr: (res.stderr || "").trim() };
+}
+
+function isLoaded() {
+  if (!isSupported()) return false;
+  return launchctl(["print", `${domainTarget()}/${LABEL}`]).code === 0;
+}
+
+function launchdStatus() {
+  const supported = isSupported();
+  return {
+    supported,
+    installed: supported && fs.existsSync(plistPath()),
+    loaded: supported && isLoaded(),
+    plistPath: plistPath(),
+    label: LABEL,
+    entry: cliEntry(),
+  };
+}
+
+/** plist 작성 + launchctl bootstrap 로드(멱등 — 이미 로드면 bootout 후 재로드). */
+function enableLaunchd({ intervalSec = 300 } = {}) {
+  if (!isSupported()) return { ...launchdStatus(), error: "launchd persistence is macOS-only." };
+  const p = plistPath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, plistXml(intervalSec), "utf8");
+  } catch (err) {
+    return { ...launchdStatus(), error: `failed to write plist: ${String(err)}` };
+  }
+  if (isLoaded()) launchctl(["bootout", `${domainTarget()}/${LABEL}`]);
+  const res = launchctl(["bootstrap", domainTarget(), p]);
+  if (res.code !== 0 && !isLoaded()) {
+    return { ...launchdStatus(), error: res.stderr || "launchctl bootstrap failed." };
+  }
+  return launchdStatus();
+}
+
+/** launchctl bootout + plist 삭제. */
+function disableLaunchd() {
+  if (!isSupported()) return launchdStatus();
+  if (isLoaded()) launchctl(["bootout", `${domainTarget()}/${LABEL}`]);
+  const p = plistPath();
+  try { if (fs.existsSync(p)) fs.rmSync(p); }
+  catch (err) { return { ...launchdStatus(), error: `failed to remove plist: ${String(err)}` }; }
+  return launchdStatus();
+}
+
+module.exports = {
+  LABEL, plistPath, plistXml, cliEntry, isSupported,
+  launchdStatus, enableLaunchd, disableLaunchd,
+};

package/engine/bootstrap-schema.sql

@@ -412,50 +412,12 @@ CREATE TABLE automation_runs (
       , last_activity_at TEXT, occurrence_id TEXT, graph_digest TEXT, checkpoint_json TEXT, resume_of_run_id TEXT);
 CREATE INDEX idx_automation_runs_auto
         ON automation_runs(automation_id, started_at);
-CREATE TRIGGER agentlas_auto_cua_social_insert
-AFTER INSERT ON automations
-WHEN NEW.tool_mode = 'auto' AND (
-  lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%reddit%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%instagram%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%threads%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%twitter%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%x.com%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%linkedin%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%facebook%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%tiktok%'
-  OR (lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%browser%' AND lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%post%')
-  OR (lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%web%' AND lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%login%')
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%레딧%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%인스타%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%댓글%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%게시%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%로그인%'
-)
-BEGIN
-  UPDATE automations SET tool_mode = 'computer-use' WHERE id = NEW.id;
-END;
-CREATE TRIGGER agentlas_auto_cua_social_update
-AFTER UPDATE OF name, prompt_template, tool_mode ON automations
-WHEN NEW.tool_mode = 'auto' AND (
-  lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%reddit%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%instagram%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%threads%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%twitter%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%x.com%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%linkedin%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%facebook%'
-  OR lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%tiktok%'
-  OR (lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%browser%' AND lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%post%')
-  OR (lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%web%' AND lower(coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'')) LIKE '%login%')
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%레딧%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%인스타%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%댓글%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%게시%'
-  OR coalesce(NEW.name,'') || ' ' || coalesce(NEW.prompt_template,'') LIKE '%로그인%'
-)
-BEGIN
-  UPDATE automations SET tool_mode = 'computer-use' WHERE id = NEW.id;
-END;
+-- (제거됨 2026-08-06) agentlas_auto_cua_social_insert/update 트리거가 여기 있었다.
+-- 소셜 키워드 목록("twitter/인스타/댓글/게시/로그인"…)으로 tool_mode를 computer-use로
+-- 강제 되돌리던 DB 차원 단어목록 판정 — 코드의 단어목록을 LLM 판정으로 대체할 때
+-- 이 트리거만 살아남아, 코드 리뷰가 볼 수 없는 곳에서 toolMode 도출 규칙을 무효화했다
+-- (실측: UPDATE tool_mode='auto'가 같은 연결에서 즉시 되돌아왔다). 판정을 DB 트리거로
+-- 만들지 않는다 — 판정은 코드·게이트가 보는 곳에만 산다.
 CREATE TABLE agent_evolution_proposals (
         id TEXT PRIMARY KEY,
         agent_id TEXT NOT NULL,

package/engine/browser/cdp.cjs

@@ -0,0 +1,188 @@
+"use strict";
+/*
+ * browser/cdp — 터미널 명령적 브라우저 조종 (2026-08-06).
+ *
+ * 배경(오너): 데스크탑은 Electron BrowserWindow.executeJavaScript 로 페이지를
+ * 명령적으로 조종한다(navigate → innerText 읽기 → 타이핑 → 토큰 파싱). 터미널
+ * `agentlas browser` 는 리서치용(URL 읽기·검색)이라 그 명령적 조종이 없었다.
+ * 공유 CDP 엔진(browser-cdp-launcher.js)이 이미 Agentlas 전용 Chrome 을 원격
+ * 디버깅 포트(기본 9222)로 띄우므로, 그 포트에 raw CDP(DevTools Protocol)로 붙어
+ * navigate/evaluate/waitFor 를 제공한다. Node 22+ 의 global WebSocket·fetch 만
+ * 쓴다(의존성 0).
+ *
+ * evaluate(js) 는 데스크탑 executeJavaScript 와 동형(Runtime.evaluate,
+ * returnByValue + awaitPromise). BotFather 자동생성 같은 데스크탑 흐름이 이 위에
+ * 얹힌다.
+ *
+ * 안전: Agentlas 전용 프로필 Chrome 에만 붙는다(개인 크롬 아님). 되돌릴 수 없는
+ * 행동은 호출자가 판단한다 — 이 모듈은 조종 primitive 만 제공한다.
+ */
+const http = require("node:http");
+
+const DEFAULT_PORT = Number(process.env.AGENTLAS_CDP_PORT || 9222);
+
+function httpJson(port, path, { timeout = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ host: "127.0.0.1", port, path, timeout }, (res) => {
+      let body = "";
+      res.on("data", (d) => { body += d; });
+      res.on("end", () => {
+        try { resolve(JSON.parse(body)); } catch (e) { reject(e); }
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error(`CDP ${path} timed out`)); });
+  });
+}
+
+/** 9222 가 살아있나(Agentlas 전용 Chrome). */
+async function cdpReady(port = DEFAULT_PORT) {
+  try { await httpJson(port, "/json/version"); return true; } catch { return false; }
+}
+
+/** 조종할 page 타겟 하나를 고른다(없으면 새로 연다). 반환: webSocketDebuggerUrl. */
+async function pickPageTarget(port = DEFAULT_PORT) {
+  const targets = await httpJson(port, "/json");
+  let page = (Array.isArray(targets) ? targets : []).find((t) => t.type === "page" && t.webSocketDebuggerUrl);
+  if (!page) {
+    // 새 탭을 연다(DevTools HTTP: PUT /json/new).
+    page = await httpJson(port, "/json/new?about:blank");
+  }
+  if (!page || !page.webSocketDebuggerUrl) throw new Error("no CDP page target available");
+  return page.webSocketDebuggerUrl;
+}
+
+/**
+ * 페이지 하나에 CDP 로 붙는다. 반환: { navigate, evaluate, waitFor, close }.
+ * primitive:
+ *   navigate(url)                 Page.navigate + load 대기(간이)
+ *   evaluate(js, {awaitPromise})  Runtime.evaluate(returnByValue) — 값 반환
+ *   waitFor(jsPredicate, {timeoutMs, pollMs})  predicate 가 truthy 될 때까지
+ */
+async function attachPage({ port = DEFAULT_PORT, wsUrl } = {}) {
+  const url = wsUrl || (await pickPageTarget(port));
+  const ws = new WebSocket(url);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener("open", resolve, { once: true });
+    ws.addEventListener("error", () => reject(new Error("CDP websocket failed to open")), { once: true });
+  });
+
+  let nextId = 0;
+  const pending = new Map();
+  ws.addEventListener("message", (event) => {
+    let msg;
+    try { msg = JSON.parse(typeof event.data === "string" ? event.data : String(event.data)); } catch { return; }
+    if (msg.id != null && pending.has(msg.id)) {
+      const { resolve, reject } = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) reject(Object.assign(new Error(msg.error.message || "CDP error"), { cdp: msg.error }));
+      else resolve(msg.result);
+    }
+  });
+
+  function send(method, params = {}, { timeout = 30000 } = {}) {
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error(`CDP ${method} timed out`)); }, timeout);
+      pending.set(id, {
+        resolve: (r) => { clearTimeout(timer); resolve(r); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+      });
+      ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  await send("Page.enable").catch(() => {});
+  await send("Runtime.enable").catch(() => {});
+
+  async function evaluate(expression, { awaitPromise = true } = {}) {
+    const res = await send("Runtime.evaluate", {
+      expression: `(() => { ${expression} })()`,
+      returnByValue: true,
+      awaitPromise,
+    });
+    if (res && res.exceptionDetails) {
+      throw new Error("page evaluate threw: " + (res.exceptionDetails.text || JSON.stringify(res.exceptionDetails)));
+    }
+    return res && res.result ? res.result.value : undefined;
+  }
+
+  // 편의: 표현식(값) 하나를 평가.
+  async function evalExpr(expression, opts) {
+    return evaluate(`return (${expression});`, opts);
+  }
+
+  async function navigate(target, { waitMs = 1500 } = {}) {
+    await send("Page.navigate", { url: target });
+    // 간이 로드 대기 — 필요하면 waitFor 로 정밀 대기.
+    await new Promise((r) => setTimeout(r, waitMs));
+  }
+
+  async function waitFor(predicateExpr, { timeoutMs = 60000, pollMs = 800 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      let ok = false;
+      try { ok = await evalExpr(predicateExpr); } catch { ok = false; }
+      if (ok) return true;
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    return false;
+  }
+
+  /*
+   * 진짜 조종(읽기만이 아니라 몰기). 데스크탑은 Electron sendInputEvent 로 키·클릭을
+   * 넣는다. 여기서는 CDP Input.* 로 같은 일을 한다:
+   *   focusSelector(sel)         해당 요소에 포커스(evaluate)
+   *   typeInto(sel, text)        요소에 포커스 후 Input.insertText 로 문자열 삽입
+   *   pressKey("Enter")          Input.dispatchKeyEvent (keyDown+keyUp)
+   *   clickSelector(sel)         요소를 클릭(evaluate element.click — SPA에 안정적)
+   * BotFather /newbot 같은 데스크탑 흐름이 이 위에 얹힌다.
+   */
+  const KEYS = { Enter: { key: "Enter", code: "Enter", windowsVirtualKeyCode: 13, text: "\r" } };
+
+  async function focusSelector(selector) {
+    const ok = await evaluate(`const el=document.querySelector(${JSON.stringify(selector)}); if(!el) return false; el.focus(); return true;`);
+    if (!ok) throw new Error(`no element matches ${selector}`);
+    return true;
+  }
+
+  async function typeInto(selector, text) {
+    await focusSelector(selector);
+    await send("Input.insertText", { text: String(text) });
+    return true;
+  }
+
+  async function pressKey(name) {
+    const k = KEYS[name];
+    if (!k) throw new Error(`unsupported key: ${name}`);
+    await send("Input.dispatchKeyEvent", { type: "keyDown", ...k });
+    await send("Input.dispatchKeyEvent", { type: "keyUp", ...k });
+    return true;
+  }
+
+  async function clickSelector(selector) {
+    const ok = await evaluate(`const el=document.querySelector(${JSON.stringify(selector)}); if(!el) return false; el.click(); return true;`);
+    if (!ok) throw new Error(`no element matches ${selector}`);
+    return true;
+  }
+
+  /*
+   * 현재 페이지를 PDF 로 인쇄한다(데스크탑 document/export-pdf.ts 의 offscreen
+   * BrowserWindow.printToPDF 와 같은 메커니즘 — 여기서는 CDP Page.printToPDF).
+   * base64 를 디코드해 outPath 에 쓴다. 반환: {path, bytes}.
+   */
+  async function printPdf(outPath, { landscape = false, printBackground = true, scale = 1 } = {}) {
+    const res = await send("Page.printToPDF", { landscape, printBackground, scale, transferMode: "ReturnAsBase64" }, { timeout: 60000 });
+    const b64 = res && res.data;
+    if (!b64) throw new Error("Page.printToPDF returned no data");
+    const buf = Buffer.from(b64, "base64");
+    require("node:fs").writeFileSync(outPath, buf);
+    return { path: outPath, bytes: buf.length };
+  }
+
+  function close() { try { ws.close(); } catch { /* already closed */ } }
+
+  return { navigate, evaluate, evalExpr, waitFor, focusSelector, typeInto, pressKey, clickSelector, printPdf, close, send };
+}
+
+module.exports = { cdpReady, pickPageTarget, attachPage, DEFAULT_PORT };

package/engine/browser/vault.cjs

@@ -0,0 +1,124 @@
+"use strict";
+/*
+ * browser/vault — 터미널 독립 브라우저 볼트 (2026-08-06).
+ *
+ * 배경(오너: "조종을 다른 흐름으로 확장"): 데스크탑 electron/store/browser-vault.ts 는
+ * 사이트별 전용-프로필 로그인/세션 상태를 관리한다(사이트 카드 · 세션 valid/expired/none ·
+ * 권한 · 행동 로그). 저장 테이블(browser_sites/browser_sessions/…)은 이미 터미널 부트스트랩
+ * 스키마에 있어 **데스크탑과 그대로 공유**된다. 그 핵심 CRUD 만 이식한다.
+ *
+ * 보안(데스크탑과 동일): 사이트 비밀번호를 받거나 자동 입력하지 않는다. 로그인은 제공자
+ * 페이지에서 사용자가 직접 하고, 터미널은 페이지를 열어 주고(조종) 세션 상태만 기록한다.
+ * has_password 는 항상 0 — CLI 로는 어떤 자격증명도 볼트에 들어가지 않는다.
+ */
+const crypto = require("node:crypto");
+const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
+
+function nowIso() { return new Date().toISOString(); }
+
+/** 입력을 host 로 정규화한다(데스크탑 normalizeSite 와 같은 규칙 — userinfo 는 거부). */
+function normalizeSite(input) {
+  const raw = String(input || "").trim();
+  if (!raw) return "";
+  let u;
+  try { u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`); } catch { return ""; }
+  if (u.username || u.password) return ""; // 자격증명은 사이트 키에 절대 들이지 않는다
+  const host = u.host.toLowerCase().replace(/^www\./, "");
+  return host && !/\s/.test(host) ? host : "";
+}
+
+function listBrowserSites(db) {
+  let rows;
+  try {
+    rows = db.prepare(
+      `SELECT s.id, s.site, s.label, s.username, s.created_at, s.updated_at,
+              se.status AS sess_status, se.captured_at AS sess_captured
+       FROM browser_sites s
+       LEFT JOIN browser_sessions se ON se.site = s.site
+       ORDER BY s.updated_at DESC`,
+    ).all();
+  } catch { return []; }
+  return rows.map((r) => ({
+    id: String(r.id),
+    site: String(r.site),
+    label: r.label ?? null,
+    username: r.username ?? null,
+    session: { status: r.sess_status ?? "none", capturedAt: r.sess_captured ?? null },
+    createdAt: String(r.created_at),
+    updatedAt: String(r.updated_at),
+  }));
+}
+
+function getBrowserSite(db, site) {
+  const norm = normalizeSite(site);
+  return listBrowserSites(db).find((s) => s.site === norm) || null;
+}
+
+/** 사이트 카드를 만들거나 갱신한다(비밀번호 없음 — has_password 항상 0). */
+function upsertBrowserSite(db, input) {
+  const site = normalizeSite(input.site);
+  if (!site) throw new Error("site address is empty or malformed");
+  const now = nowIso();
+  runWriteTransaction(db, () => {
+    const existing = db.prepare("SELECT id FROM browser_sites WHERE site = ?").get(site);
+    if (existing) {
+      db.prepare(
+        "UPDATE browser_sites SET label = COALESCE(?, label), username = COALESCE(?, username), updated_at = ? WHERE site = ?",
+      ).run(input.label ?? null, input.username ?? null, now, site);
+    } else {
+      db.prepare(
+        "INSERT INTO browser_sites (id, site, label, username, has_password, created_at, updated_at) VALUES (?,?,?,?,?,?,?)",
+      ).run(crypto.randomUUID(), site, input.label ?? null, input.username ?? null, 0, now, now);
+      db.prepare(
+        "INSERT OR IGNORE INTO browser_sessions (id, site, status, captured_at) VALUES (?, ?, 'none', NULL)",
+      ).run(crypto.randomUUID(), site);
+    }
+  });
+  return getBrowserSite(db, site);
+}
+
+function deleteBrowserSite(db, site) {
+  const norm = normalizeSite(site) || String(site || "").trim();
+  runWriteTransaction(db, () => {
+    db.prepare("DELETE FROM browser_sessions WHERE site = ?").run(norm);
+    db.prepare("DELETE FROM browser_permissions WHERE site = ?").run(norm);
+    db.prepare("DELETE FROM browser_sites WHERE site = ?").run(norm);
+  });
+  return { ok: true };
+}
+
+/** 세션 상태를 기록한다(valid 면 captured_at 을 지금으로, 아니면 비운다). 데스크탑과 동일. */
+function setBrowserSession(db, site, status) {
+  const norm = normalizeSite(site);
+  if (!norm) throw new Error("site address is empty or malformed");
+  if (status !== "valid" && status !== "expired" && status !== "none") {
+    throw new Error(`status must be valid | expired | none, got ${status}`);
+  }
+  const captured = status === "valid" ? nowIso() : null;
+  runWriteTransaction(db, () => {
+    const existing = db.prepare("SELECT id FROM browser_sessions WHERE site = ?").get(norm);
+    if (existing) {
+      db.prepare("UPDATE browser_sessions SET status = ?, captured_at = ? WHERE site = ?").run(status, captured, norm);
+    } else {
+      db.prepare("INSERT INTO browser_sessions (id, site, status, captured_at) VALUES (?,?,?,?)")
+        .run(crypto.randomUUID(), norm, status, captured);
+    }
+  });
+  return getBrowserSite(db, norm);
+}
+
+/** 되돌릴 수 없는/외부로 나가는 행동을 날짜 로그에 남긴다(데스크탑과 같은 테이블). */
+function logBrowserAction(db, { site = null, action, target = null, result = null, approval = null, meta = null } = {}) {
+  try {
+    runWriteTransaction(db, () => {
+      db.prepare(
+        "INSERT INTO browser_action_logs (id, ts, site, action, target, result, approval, meta) VALUES (?,?,?,?,?,?,?,?)",
+      ).run(crypto.randomUUID(), nowIso(), site, action, target, result, approval, meta ? JSON.stringify(meta) : null);
+    });
+  } catch { /* 로그 실패는 치명적이지 않다 */ }
+}
+
+module.exports = {
+  normalizeSite, listBrowserSites, getBrowserSite,
+  upsertBrowserSite, deleteBrowserSite, setBrowserSession, logBrowserAction,
+};