agentlas 0.9.10 → 1.0.2

package/engine/agents/files.cjs

@@ -0,0 +1,61 @@
+"use strict";
+/*
+ * agents/files — 에이전트의 로컬 폴더 해석 + 네이티브 CLI 문맥 파일 생성.
+ * 폴더 우선순위: 로컬 임포트 라우트 → 클라우드 설치본(cloud-agent-installs, 복원 마커
+ * 존재 시) → userData/agents/<slug>. v1 agentFolder와 동일 규칙 — cd/native가
+ * 관찰상 읽기 전용으로 유지돼야 소스 패키지를 재분류하지 않는다.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { userDataDir } = require("../core/paths.cjs");
+const { routesMap } = require("./routes.cjs");
+
+const CLOUD_RESTORE_MARKER_PATH = ".agentlas-cloud-package.json";
+
+function cloudSlug(value) {
+  return (String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "agentlas-cloud-agent");
+}
+
+function exists(p) { try { fs.accessSync(p); return true; } catch { return false; } }
+
+function agentSystemPrompt(agent) {
+  return agent && agent.systemPrompt ? agent.systemPrompt : `You are ${(agent && agent.name) || "an Agentlas agent"}.`;
+}
+
+function agentFolder(agent) {
+  const routes = routesMap();
+  const r = routes[agent.id];
+  if (r && r.path) return r.path; // 로컬 임포트는 원본 폴더
+  const cloudRoot = path.join(userDataDir(), "cloud-agent-installs", cloudSlug(agent.slug));
+  if (exists(path.join(cloudRoot, CLOUD_RESTORE_MARKER_PATH))) return cloudRoot;
+  return path.join(userDataDir(), "agents", agent.slug);
+}
+
+function writeIfMissing(file, content) {
+  try { fs.lstatSync(file); return false; } catch (error) {
+    if (!error || error.code !== "ENOENT") throw error;
+  }
+  const fd = fs.openSync(file, "wx", 0o600);
+  try {
+    fs.writeFileSync(fd, content.endsWith("\n") ? content : content + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return true;
+}
+
+function ensureNativeFiles(agent, folder) {
+  fs.mkdirSync(folder, { recursive: true });
+  const sys = agentSystemPrompt(agent);
+  const created = [];
+  if (writeIfMissing(path.join(folder, "system-prompt.md"), sys)) created.push("system-prompt.md");
+  const header = `# ${agent.name}\n\n${agent.tagline || ""}\n\n${sys}\n`;
+  // 네이티브 CLI가 프로젝트 지시로 자동 인식하는 파일들
+  if (writeIfMissing(path.join(folder, "CLAUDE.md"), header)) created.push("CLAUDE.md");
+  if (writeIfMissing(path.join(folder, "AGENTS.md"), header)) created.push("AGENTS.md");
+  if (writeIfMissing(path.join(folder, "GEMINI.md"), header)) created.push("GEMINI.md");
+  return created;
+}
+
+module.exports = { agentFolder, ensureNativeFiles, agentSystemPrompt, cloudSlug, CLOUD_RESTORE_MARKER_PATH };

package/engine/agents/import-local.cjs

@@ -0,0 +1,237 @@
+"use strict";
+/*
+ * agents/import-local — 로컬 폴더 임포트 (데스크탑 electron/agents/import-local.ts 와 동일 규칙).
+ * 터미널에서 "폴더 드래그" = `agentlas import <path>`. 앱과 같은 DB/라우트를 공유한다.
+ * v1 모놀리스 890–1112 구간의 충실 이식 — 규칙 변경 금지(데스크탑과 판정 동형이어야 함).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { tableExists, columnExists } = require("../core/db.cjs");
+const { routesMap, saveRoutes } = require("./routes.cjs");
+
+function exists(p) { try { fs.accessSync(p); return true; } catch { return false; } }
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+function readFileSafe(p, maxChars) {
+  try { const s = fs.readFileSync(p, "utf8"); return maxChars ? s.slice(0, maxChars) : s; } catch { return ""; }
+}
+function readFirst(dir, names, maxChars) {
+  for (const n of names) {
+    const p = path.join(dir, n);
+    if (exists(p) && !isDir(p)) { const s = readFileSafe(p, maxChars || 8000); if (s) return s; }
+  }
+  return "";
+}
+
+function detectRuntimeLabels(dir) {
+  const labels = [];
+  if (exists(path.join(dir, "CLAUDE.md")) || isDir(path.join(dir, ".claude"))) labels.push("claude-code");
+  if (exists(path.join(dir, "AGENTS.md"))) labels.push("codex");
+  if (exists(path.join(dir, "GEMINI.md"))) labels.push("gemini");
+  if (isDir(path.join(dir, ".cursor")) || exists(path.join(dir, ".cursorrules"))) labels.push("cursor");
+  if (!labels.length) labels.push("generic");
+  return labels;
+}
+
+// 팀 감지 — 루트뿐 아니라 .claude/ 중첩 구조도 인식한다 (appbridge 처럼).
+function detectKind(dir) {
+  const rootMarkers = ["TEAM.md", "ceo", "hr-departments", "projects"];
+  for (const m of rootMarkers) if (exists(path.join(dir, m))) return "team";
+  const nestedMarkers = [".claude/ceo", ".claude/hr-departments", ".claude/agents", ".claude/orgspec.yaml"];
+  for (const m of nestedMarkers) if (exists(path.join(dir, m))) return "team";
+  return "agent";
+}
+
+function readImportName(dir) {
+  const text = readFirst(dir, ["manifest.md", "AGENT.md", "CLAUDE.md", "README.md"], 2000);
+  const m = text.match(/^#\s+(.+)$/m);
+  if (m) { const n = m[1].replace(/\(.*?\)/g, "").trim().slice(0, 60); if (n) return n; }
+  return path.basename(dir);
+}
+
+function readImportTagline(dir) {
+  const text = readFirst(dir, ["README.md", "soul.md", "AGENT.md"], 2000);
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.slice(0, 140);
+  }
+  // 팀 orgspec mission 첫 줄 fallback
+  const org = readFileSafe(path.join(dir, ".claude", "orgspec.yaml"), 4000);
+  const mm = org.match(/mission:\s*\|?\s*\n?\s*(.+)/);
+  if (mm) return mm[1].trim().slice(0, 140);
+  return "";
+}
+
+const IMPORT_ENV_RE = /\b[A-Z][A-Z0-9_]{2,}(?:API_KEY|TOKEN|SECRET|PASSWORD|CLIENT_ID|CLIENT_SECRET|ACCESS_TOKEN|REFRESH_TOKEN|PRIVATE_KEY|SERVICE_ACCOUNT|WEBHOOK_SECRET|CREDENTIALS|KEY)\b/g;
+const IMPORT_PROCESS_ENV_RE = /process\.env\.([A-Z][A-Z0-9_]{2,})/g;
+const IMPORT_DOTENV_LINE_RE = /^(?:export\s+)?([A-Z][A-Z0-9_]{2,})\s*=/gm;
+const IMPORT_ENV_IGNORES = new Set(["CI", "HOME", "LANG", "NODE_ENV", "PATH", "PORT", "PWD", "SHELL", "TERM", "TMPDIR", "USER"]);
+
+function detectImportEnvRequirements(dir, extraText) {
+  const files = [".env", ".env.local", ".env.example", ".env.sample", ".env.template", "env.example", "README.md", "AGENT.md", "AGENTS.md", "CLAUDE.md", "GEMINI.md", "manifest.md", "package.json", ".mcp.json"];
+  const found = new Map();
+  const add = (key, source, required) => {
+    if (!key || IMPORT_ENV_IGNORES.has(key) || key.length < 4 || key.length > 96 || !/^[A-Z][A-Z0-9_]+$/.test(key)) return;
+    const entry = found.get(key) || { sources: new Set(), required: false };
+    entry.sources.add(source);
+    entry.required = entry.required || required;
+    found.set(key, entry);
+  };
+  const collect = (text, source) => {
+    if (!text) return;
+    for (const m of text.matchAll(IMPORT_DOTENV_LINE_RE)) add(m[1], source, true);
+    for (const m of text.matchAll(IMPORT_PROCESS_ENV_RE)) add(m[1], source, true);
+    for (const m of text.matchAll(IMPORT_ENV_RE)) add(m[0], source, source.includes(".env"));
+  };
+  for (const name of files) collect(readFileSafe(path.join(dir, name), 256 * 1024), name);
+  collect(extraText || "", "system prompt");
+  return [...found.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, info]) => ({
+    key,
+    label: key.replace(/_/g, " ").toLowerCase().replace(/\b\w/g, (ch) => ch.toUpperCase()),
+    labelEn: key.replace(/_/g, " ").toLowerCase().replace(/\b\w/g, (ch) => ch.toUpperCase()),
+    required: info.required,
+    hint: "Detected in " + [...info.sources].slice(0, 3).join(", "),
+    hintEn: "Detected in " + [...info.sources].slice(0, 3).join(", "),
+  }));
+}
+
+// 팀이면 CEO 두뇌를 시스템 프롬프트로 잡고, 임의 cwd에서도 동작하도록 절대경로 헤더를 붙인다.
+function buildImportSystemPrompt(dir, name, kind) {
+  if (kind === "team") {
+    const ceoBrain = readFileSafe(path.join(dir, ".claude", "ceo", "AGENT.md"));
+    const rootAgents = readFileSafe(path.join(dir, "AGENTS.md"));
+    const rootClaude = readFileSafe(path.join(dir, "CLAUDE.md"));
+    const nestedClaude = readFileSafe(path.join(dir, ".claude", "CLAUDE.md"));
+    const brain = ceoBrain || rootAgents || rootClaude || nestedClaude;
+    const claudeRoot = path.join(dir, ".claude");
+    const header =
+      `You are the CEO / orchestrator of the "${name}" agent team, now launched through Agentlas.\n\n` +
+      `TEAM ROOT: ${dir}\n` +
+      `Team definition (org spec, playbooks, department & role agents) lives under: ${claudeRoot}\n` +
+      `When the instructions below reference team files with relative paths (e.g. ./playbook.md, ../orgspec.yaml, .claude/...), resolve them as ABSOLUTE paths under that team root and read them as needed.\n\n` +
+      `TARGET PROJECT: your current working directory is the user's target project. Do ALL building, file creation, and delivery in the current working directory — never inside the team root. Route work to the right department/specialist, sequence multi-step work, keep a brief CEO-style status in Korean, and apply read-only-first safety gates for high-risk actions (billing/auth/security/deploy).\n\n` +
+      `--- TEAM BRAIN ---\n`;
+    return (header + (brain || `Act as the orchestrating CEO of ${name}.`)).slice(0, 16000);
+  }
+  const sys = readFirst(dir, ["system-prompt.md", "soul.md", "AGENT.md", "CLAUDE.md", "AGENTS.md", "GEMINI.md"]);
+  return sys || `You are ${name}, a locally imported agent.`;
+}
+
+function readTeamDepartments(dir) {
+  for (const root of [path.join(dir, "hr-departments"), path.join(dir, ".claude", "hr-departments")]) {
+    try {
+      if (isDir(root)) {
+        return fs.readdirSync(root, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+          .map((e) => e.name).sort();
+      }
+    } catch { /* continue */ }
+  }
+  return [];
+}
+
+function deptLabel(name) {
+  return name.replace(/[-_]+/g, " ").split(" ").filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
+// 팀 폴더 → 회사(firm) upsert (앱의 upsertLocalTeamFirm 과 동일). slug 기준 멱등.
+function upsertLocalTeamFirm(db, dir, ceoAgentId, agentSlug, name, tagline) {
+  if (!tableExists(db, "firms")) return null;
+  const depts = readTeamDepartments(dir);
+  const orgChart = [
+    { agentSlug, agentId: ceoAgentId, role: "CEO", reportsTo: null },
+    ...depts.map((d) => ({ agentSlug: `${agentSlug}-${d}`, agentId: "", role: deptLabel(d), reportsTo: agentSlug })),
+  ];
+  const firmSlug = `firm-${agentSlug}`;
+  const chartJson = JSON.stringify(orgChart);
+  const existing = db.prepare("SELECT id FROM firms WHERE slug=?").get(firmSlug);
+  if (existing) {
+    db.prepare("UPDATE firms SET name=?, name_en=?, tagline=?, tagline_en=?, persona=?, ceo_agent_id=?, org_chart_json=? WHERE id=?")
+      .run(name, name, tagline, tagline, "", ceoAgentId, chartJson, existing.id);
+    return { id: existing.id, slug: firmSlug };
+  }
+  const id = crypto.randomUUID();
+  db.prepare(
+    "INSERT INTO firms (id, slug, name, name_en, tagline, tagline_en, persona, ceo_agent_id, org_chart_json, installed_at) VALUES (?,?,?,?,?,?,?,?,?,?)",
+  ).run(id, firmSlug, name, name, tagline, tagline, "", ceoAgentId, chartJson, new Date().toISOString());
+  return { id, slug: firmSlug };
+}
+
+function importLocalFolder(db, absPath) {
+  const dir = path.resolve(absPath);
+  if (!isDir(dir)) throw new Error(`Not a directory: ${absPath}`);
+  const labels = detectRuntimeLabels(dir);
+  const runtime = labels[0];
+  const kind = detectKind(dir);
+  const name = readImportName(dir);
+  const tagline = readImportTagline(dir) || (kind === "team" ? "Imported local team" : "Imported local agent");
+  const systemPrompt = buildImportSystemPrompt(dir, name, kind);
+  const envRequirements = detectImportEnvRequirements(dir, systemPrompt);
+  const envReqsJson = JSON.stringify(envRequirements);
+
+  // 같은 경로가 이미 임포트돼 있으면 그 에이전트를 갱신(멱등).
+  const routes = routesMap();
+  let existingId = null;
+  for (const [aid, r] of Object.entries(routes)) {
+    if (r && path.resolve(r.path || "") === dir) { existingId = aid; break; }
+  }
+  const now = new Date().toISOString();
+  const TONES = ["blue", "green", "purple", "amber", "peach"];
+  let id, slug;
+  if (existingId) {
+    id = existingId;
+    const row = db.prepare("SELECT slug FROM installed_agents WHERE id=?").get(id);
+    slug = row ? row.slug : null;
+    if (slug) {
+      if (columnExists(db, "installed_agents", "visibility")) {
+        db.prepare("UPDATE installed_agents SET name=?, name_en=?, tagline=?, tagline_en=?, system_prompt=?, env_requirements_json=?, visibility='visible' WHERE id=?")
+          .run(name, name, tagline, tagline, systemPrompt, envReqsJson, id);
+      } else {
+        db.prepare("UPDATE installed_agents SET name=?, name_en=?, tagline=?, tagline_en=?, system_prompt=?, env_requirements_json=? WHERE id=?")
+          .run(name, name, tagline, tagline, systemPrompt, envReqsJson, id);
+      }
+    } else { existingId = null; }
+  }
+  if (!existingId) {
+    const base = "local-" + (path.basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "agent");
+    slug = base; let n = 1;
+    while (db.prepare("SELECT 1 FROM installed_agents WHERE slug=?").get(slug)) slug = `${base}-${++n}`;
+    id = crypto.randomUUID();
+    let h = 0; for (let i = 0; i < slug.length; i++) h = (h << 5) - h + slug.charCodeAt(i);
+    const tone = TONES[Math.abs(h) % TONES.length];
+    if (columnExists(db, "installed_agents", "visibility")) {
+      db.prepare(
+        "INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, builtin, visibility) VALUES (?,?,?,?,?,?,?,'[]',?,NULL,'A',?,?,0,'visible')",
+      ).run(id, slug, name, name, tagline, tagline, systemPrompt, envReqsJson, now, tone);
+    } else {
+      db.prepare(
+        "INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, builtin) VALUES (?,?,?,?,?,?,?,'[]',?,NULL,'A',?,?,0)",
+      ).run(id, slug, name, name, tagline, tagline, systemPrompt, envReqsJson, now, tone);
+    }
+  }
+  // detectKind 결과를 DB에도 기록 — needsImage의 팀 body-veto 등 능력 판정이
+  // 데스크탑이 써준 entity_kind에 무임승차하지 않고 터미널 단독 임포트에서도 성립한다.
+  if (columnExists(db, "installed_agents", "entity_kind")) {
+    db.prepare("UPDATE installed_agents SET entity_kind=? WHERE id=?").run(kind, id);
+  }
+  // 라우트 저장
+  routes[id] = { agentId: id, path: dir, runtime, labels, kind, importedAt: now };
+  saveRoutes(routes);
+
+  // 팀이면 회사(firm)로도 등록 → 앱 FIRMS 목록 + `agentlas firm <slug>` 사용 가능. slug 기준 멱등.
+  let firm = null;
+  if (kind === "team") {
+    try { firm = upsertLocalTeamFirm(db, dir, id, slug, name, tagline); } catch { /* best-effort */ }
+  }
+  return { id, slug, name, tagline, runtime, labels, kind, path: dir, updated: !!existingId, firmSlug: firm ? firm.slug : null };
+}
+
+module.exports = {
+  importLocalFolder,
+  detectKind,
+  detectRuntimeLabels,
+  detectImportEnvRequirements,
+  buildImportSystemPrompt,
+  upsertLocalTeamFirm,
+};

package/engine/agents/registry.cjs

@@ -0,0 +1,158 @@
+"use strict";
+/*
+ * agents/registry — 설치 에이전트 조회 (공유 DB 읽기 전용 표면).
+ * 라우팅/판정은 여기 없다 — 이 모듈은 결정론적 조회만 한다.
+ *
+ * 프라이버시 정책(v1/데스크탑 동형): 일부 아키텍처 에이전트는 웹 전용(private) 또는
+ * 백그라운드 인프라라서 목록/해석에서 제외된다. visibility 열 + 역할 + 정규화 지문
+ * 셋으로 판정한다 — 지문 셋은 이름이 리브랜딩돼도 구본을 계속 가리기 위한 것.
+ */
+const crypto = require("node:crypto");
+
+const PRIVATE_WEB_AGENT_FINGERPRINTS = new Set([
+  "880db20e11cd945e5777b5aaf73c10f24de3e2e190d13631b5f3ed0e4796821c",
+  "a0dba10416f15dac84202902284780ee23f31eda9dc068ccf6a28276b585ea36",
+  "479d879189166bf9bde1b0cd939db746bf8c1b94f2aad553d08cf7b4a2204f9e",
+  "79c16e0347312aceb57c0ec7ee6bb6ebd0118984cc716f9cd56db63d18679183",
+  "56ff55fcc909461b5fc449fdb3d685c6cceeb10d59836d9a91faf3ceb41896a4",
+  "978dd8a262d86397bbdaca13bbec5be313a68fb2d5c609330888818641af8079",
+]);
+const BACKGROUND_AGENT_FINGERPRINTS = new Set([
+  "9011fb75e638676e23a36f86ea689b6e4de17cb5b5954b36810b5239ab077f0b",
+  "0331d654916d648797d31598e3e18eb7fd49166e91783ab9d731648b6e855b90",
+]);
+const BACKGROUND_ROLES = new Set(["orchestrator", "pm", "curator", "governance"]);
+// 데스크탑 electron/agents/policy.ts:35 REMOVED_MARKETPLACE_SEED_SLUGS 동형 —
+// 마켓에서 회수된 시드 에이전트는 publicAgentVisibility가 무조건 'private'으로
+// 강등한다(electron/agents/policy.ts:96). 데스크탑은 db.ts:1499에서 이 값을
+// visibility 열에 백필하지만, 데스크탑 마이그레이션이 안 돈 DB에서 터미널이
+// 이 목록 없이 읽으면 회수된 시드가 목록/해석에 다시 새어 나온다.
+const REMOVED_MARKETPLACE_SEED_SLUGS = new Set([
+  "shop-product-writer",
+  "shop-cs-responder",
+  "shop-review-monitor",
+  "shop-pricing-scout",
+  "shop-keyword-finder",
+  "marketer-content-writer",
+  "marketer-seo-researcher",
+  "marketer-schedule-secretary",
+  "marketer-ad-copywriter",
+  "marketer-analytics-reader",
+  "firm-ceo-shop",
+  "firm-ceo-marketer",
+]);
+
+function policyNormalize(value) {
+  return String(value || "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function policyFingerprint(value) {
+  const normalized = policyNormalize(value);
+  return normalized ? crypto.createHash("sha256").update(normalized).digest("hex") : null;
+}
+function agentRowFingerprints(row) {
+  return [row.slug, row.name, row.name_en, row.tagline, row.tagline_en]
+    .map(policyFingerprint)
+    .filter(Boolean);
+}
+function isPrivateWebOnlyAgentRow(row) {
+  if (policyNormalize(row.visibility) === "private") return true;
+  if (policyNormalize(row.role) === "meta") return true;
+  return agentRowFingerprints(row).some((value) => PRIVATE_WEB_AGENT_FINGERPRINTS.has(value));
+}
+function isBackgroundAgentRow(row) {
+  if (isPrivateWebOnlyAgentRow(row)) return false;
+  if (policyNormalize(row.visibility) === "background") return true;
+  if (row.builtin && BACKGROUND_ROLES.has(policyNormalize(row.role))) return true;
+  return agentRowFingerprints(row).some((value) => BACKGROUND_AGENT_FINGERPRINTS.has(value));
+}
+
+/**
+ * 데스크탑 publicAgentVisibility 동형 (electron/agents/policy.ts:95-100):
+ * 회수된 마켓 시드 슬러그 → private (지문/역할 검사보다 먼저),
+ * 웹 전용 → private, 백그라운드 → background, 그 외 → 열 값(없으면 visible).
+ */
+function publicAgentVisibilityRow(row) {
+  if (REMOVED_MARKETPLACE_SEED_SLUGS.has(policyNormalize(row.slug))) return "private";
+  if (isPrivateWebOnlyAgentRow(row)) return "private";
+  if (isBackgroundAgentRow(row)) return "background";
+  const declared = policyNormalize(row.visibility);
+  return declared === "visible" || declared === "background" || declared === "private" ? declared : "visible";
+}
+
+function rowToAgent(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    nameEn: row.name_en || "",
+    tagline: row.tagline || "",
+    taglineEn: row.tagline_en || "",
+    systemPrompt: row.system_prompt || "",
+    preferredBackend: row.preferred_backend || null,
+    builtin: !!row.builtin,
+    visibility: row.visibility || "visible",
+    role: row.role || null,
+    mcpServersJson: row.mcp_servers_json || "[]",
+  };
+}
+
+/** 웹 전용(private)·회수 시드 제외 전체 목록 — 백그라운드 인프라는 visibility='background'로 정규화. */
+function listPublicAgents(db) {
+  return db.prepare("SELECT * FROM installed_agents ORDER BY installed_at DESC").all()
+    .filter((row) => publicAgentVisibilityRow(row) !== "private")
+    .map((row) => rowToAgent({ ...row, visibility: isBackgroundAgentRow(row) ? "background" : "visible" }));
+}
+
+function listAgents(db) {
+  return listPublicAgents(db).filter((agent) => agent.visibility !== "background");
+}
+
+/** 라우팅 후보(백그라운드 포함, 웹 전용 제외). */
+function listRoutableAgents(db) {
+  return listPublicAgents(db);
+}
+
+/**
+ * slug/이름 해석 — 라우팅 가능 집합(listRoutableAgents) 안에서만 찾는다:
+ * 웹 전용(private) 에이전트는 이름을 알아도 터미널에서 실행되면 안 된다.
+ * 정확 일치 → 유일 부분 일치. 부분 일치가 여럿이면 모호 — 조용히 고르지 않는다.
+ */
+function findAgent(db, token) {
+  const q = String(token || "").trim().toLowerCase();
+  if (!q) return null;
+  const agents = listRoutableAgents(db);
+  const exact = agents.find((a) => a.slug.toLowerCase() === q || a.id === token)
+    || agents.find((a) => (a.name || "").toLowerCase() === q || (a.nameEn || "").toLowerCase() === q);
+  if (exact) return exact;
+  const partial = agents.filter((a) =>
+    a.slug.toLowerCase().includes(q) || (a.name || "").toLowerCase().includes(q) || (a.nameEn || "").toLowerCase().includes(q));
+  if (partial.length === 1) return partial[0];
+  return null;
+}
+
+function agentMcpServerIds(db, agentId) {
+  try {
+    return db.prepare("SELECT server_id FROM agent_mcp_servers WHERE agent_id=?").all(agentId).map((r) => r.server_id);
+  } catch {
+    return [];
+  }
+}
+
+/** invoke 시스템 프롬프트: 저장 프롬프트가 없으면 이름 기반 최소 프롬프트 (v1 agentSystemPromptCli 동형). */
+function agentSystemPrompt(row) {
+  return row && row.system_prompt ? row.system_prompt : `You are ${row?.name || "an Agentlas agent"}.`;
+}
+
+module.exports = {
+  findAgent,
+  listAgents,
+  listPublicAgents,
+  listRoutableAgents,
+  rowToAgent,
+  agentMcpServerIds,
+  agentSystemPrompt,
+  isPrivateWebOnlyAgentRow,
+  isBackgroundAgentRow,
+  publicAgentVisibilityRow,
+};