agentlas 1.0.28 → 1.0.35

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,
+};

package/engine/cli-output.cjs

@@ -0,0 +1,262 @@
+"use strict";
+/*
+ * CLI 출력 계약 — 명령은 **문자열이 아니라 {데이터 + 스키마}** 를 돌려준다.
+ *
+ * 왜(2026-08-08, Paseo CLI 대조 실측):
+ * 우리 명령들은 각자 `ctx.out("...")` 로 직접 찍었다. 그래서
+ *  · `--json` 이 어떤 명령엔 있고 어떤 명령엔 없다,
+ *  · 에러 형식이 명령마다 다르다,
+ *  · 스크립트가 쓰려면 사람용 문장을 파싱해야 한다.
+ *
+ * Paseo CLI(`packages/cli/src/output/`)는 명령이 `{type,data,schema}` 를 반환하고
+ * 렌더러 하나가 `--json/--yaml/--quiet/--no-color/--no-headers` 를 해석한다.
+ * 그 계약을 그대로 가져온다. 규칙 셋:
+ *
+ *  1. **quiet 이 모든 것을 이긴다.** `--quiet` 는 id 만 한 줄씩 — `xargs` 로 바로 흐른다.
+ *  2. **에러도 같은 형식 규율을 따른다.** `--json` 이면 `{"error":{"code","message"}}`.
+ *     사람용이면 빨간 `Error: `.
+ *  3. **색은 옵션이 정한다.** 명령이 직접 ANSI 를 박지 않는다(파이프 오염 금지).
+ *
+ * 이 파일은 의존성이 없다(테스트가 순수 함수로 검증한다).
+ */
+
+/** @typedef {"table"|"json"|"yaml"} OutputFormat */
+
+const DEFAULT_OPTIONS = Object.freeze({
+  format: "table",
+  quiet: false,
+  noHeaders: false,
+  noColor: false,
+});
+
+/** 명령이 돌려주는 단일 항목 결과. */
+function single(data, schema) {
+  return { type: "single", data, schema };
+}
+
+/** 명령이 돌려주는 목록 결과. */
+function list(data, schema) {
+  return { type: "list", data: Array.isArray(data) ? data : [], schema };
+}
+
+function isResult(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value.type === "single" || value.type === "list") &&
+      value.schema &&
+      Array.isArray(value.schema.columns),
+  );
+}
+
+function rowsOf(result) {
+  return result.type === "list" ? result.data : [result.data];
+}
+
+function readField(item, field) {
+  if (typeof field === "function") return field(item);
+  if (item && typeof item === "object") return item[field];
+  return undefined;
+}
+
+function textOf(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return JSON.stringify(value);
+}
+
+/**
+ * 표시 폭 — ANSI 를 벗기고, CJK 전각을 2칸으로 센다.
+ * 한글 표가 어긋나던 이유가 이것이다(폭을 문자 수로 세면 열이 밀린다).
+ */
+function displayWidth(value) {
+  const plain = String(value).replace(/\[[0-9;]*m/g, "");
+  let width = 0;
+  for (const char of plain) {
+    const code = char.codePointAt(0) ?? 0;
+    const wide =
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x2e80 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+function padTo(value, width, align) {
+  const pad = Math.max(0, width - displayWidth(value));
+  if (align === "right") return " ".repeat(pad) + value;
+  if (align === "center") {
+    const left = Math.floor(pad / 2);
+    return " ".repeat(left) + value + " ".repeat(pad - left);
+  }
+  return value + " ".repeat(pad);
+}
+
+function renderQuiet(result) {
+  const idField = result.schema.idField;
+  return rowsOf(result)
+    .map((item) => textOf(readField(item, idField)))
+    .filter((line) => line.length > 0)
+    .join("\n");
+}
+
+function renderJson(result) {
+  const serialize = result.schema.serialize;
+  const project = (item) => (serialize ? serialize(item) : item);
+  const payload = result.type === "list" ? result.data.map(project) : project(result.data);
+  return JSON.stringify(payload, null, 2);
+}
+
+/** 의존성 없이 쓰는 최소 YAML(스칼라·객체·배열 1단계). */
+function renderYaml(result) {
+  const serialize = result.schema.serialize;
+  const project = (item) => (serialize ? serialize(item) : item);
+  const scalar = (value) => {
+    if (value === null || value === undefined) return "null";
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    const text = textOf(value);
+    return /^[\w./:@-]+$/.test(text) ? text : JSON.stringify(text);
+  };
+  const objectLines = (object, indent) => {
+    const pad = " ".repeat(indent);
+    return Object.entries(object).map(([key, value]) => {
+      if (value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date)) {
+        return `${pad}${key}:\n${objectLines(value, indent + 2).join("\n")}`;
+      }
+      if (Array.isArray(value)) {
+        if (value.length === 0) return `${pad}${key}: []`;
+        return `${pad}${key}:\n${value.map((entry) => `${pad}  - ${scalar(entry)}`).join("\n")}`;
+      }
+      return `${pad}${key}: ${scalar(value)}`;
+    });
+  };
+  if (result.type === "list") {
+    if (result.data.length === 0) return "[]";
+    return result.data
+      .map((item) => {
+        const lines = objectLines(project(item), 2);
+        return `- ${lines.join("\n").trimStart()}`;
+      })
+      .join("\n");
+  }
+  return objectLines(project(result.data), 0).join("\n");
+}
+
+function renderTable(result, options) {
+  const columns = result.schema.columns;
+  const rows = rowsOf(result);
+  if (rows.length === 0) return "";
+  const cells = rows.map((item) =>
+    columns.map((column) => textOf(readField(item, column.field))),
+  );
+  const widths = columns.map((column, index) =>
+    Math.max(
+      options.noHeaders ? 0 : displayWidth(column.header),
+      ...cells.map((row) => displayWidth(row[index] ?? "")),
+    ),
+  );
+  const lines = [];
+  if (!options.noHeaders) {
+    lines.push(
+      columns
+        .map((column, index) => padTo(column.header.toUpperCase(), widths[index], column.align))
+        .join("  ")
+        .trimEnd(),
+    );
+  }
+  for (const row of cells) {
+    lines.push(
+      columns
+        .map((column, index) => padTo(row[index] ?? "", widths[index], column.align))
+        .join("  ")
+        .trimEnd(),
+    );
+  }
+  return lines.join("\n");
+}
+
+/** 형식 선택은 여기 한 곳. quiet 이 언제나 이긴다. */
+function render(result, options = {}) {
+  if (!isResult(result)) {
+    throw new TypeError("render() expects a {type,data,schema} command result");
+  }
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  if (opts.quiet) return renderQuiet(result);
+  if (opts.format === "json") return renderJson(result);
+  if (opts.format === "yaml") return renderYaml(result);
+  if (typeof result.schema.renderHuman === "function") return result.schema.renderHuman(result, opts);
+  return renderTable(result, opts);
+}
+
+/** 무엇이든 구조화 에러로. code 는 기계가 분기할 값이다. */
+function toCommandError(error) {
+  if (error && typeof error === "object" && typeof error.code === "string" && typeof error.message === "string") {
+    return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
+  }
+  if (error instanceof Error) {
+    return { code: "unknown_error", message: error.message, ...(error.stack ? { details: error.stack } : {}) };
+  }
+  return { code: "unknown_error", message: String(error) };
+}
+
+/** 에러도 같은 형식 규율을 따른다 — 사람용만 색을 쓴다. */
+function renderError(error, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const commandError = toCommandError(error);
+  if (opts.format === "json") return JSON.stringify({ error: commandError }, null, 2);
+  if (opts.format === "yaml") {
+    return ["error:", `  code: ${commandError.code}`, `  message: ${JSON.stringify(commandError.message)}`].join("\n");
+  }
+  const prefix = opts.noColor ? "Error: " : "Error: ";
+  return commandError.details && typeof commandError.details === "string" && opts.format === "table"
+    ? `${prefix}${commandError.message}`
+    : `${prefix}${commandError.message}`;
+}
+
+/**
+ * argv 에서 전역 출력 플래그를 뜯어낸다. **모든 명령이 같은 이름·같은 의미**를 갖도록
+ * 파서가 한 곳이다(명령마다 --json 유무가 갈리던 것을 막는다).
+ *
+ * 색 규칙은 clig.dev 를 따른다: `NO_COLOR` 환경변수, `--no-color`, 그리고 TTY 가
+ * 아니면 자동으로 끈다(파이프에 ANSI 를 흘리지 않는다).
+ */
+function parseOutputFlags(argv, env = process.env, isTty = Boolean(process.stdout.isTTY)) {
+  const rest = [];
+  const options = { ...DEFAULT_OPTIONS };
+  for (const token of argv) {
+    if (token === "--json") options.format = "json";
+    else if (token === "--yaml") options.format = "yaml";
+    else if (token === "--quiet" || token === "-q") options.quiet = true;
+    else if (token === "--no-headers") options.noHeaders = true;
+    else if (token === "--no-color") options.noColor = true;
+    else rest.push(token);
+  }
+  if (env && (env.NO_COLOR || env.AGENTLAS_NO_COLOR)) options.noColor = true;
+  if (!isTty) options.noColor = true;
+  return { options, rest };
+}
+
+/** 사람용 표현이 스피너·배너를 써도 되는가(비대화형이면 평문으로 떨어진다). */
+function isRichUi(options, isTty = Boolean(process.stdout.isTTY)) {
+  return Boolean(isTty) && options.format === "table" && !options.quiet;
+}
+
+module.exports = {
+  DEFAULT_OPTIONS,
+  single,
+  list,
+  isResult,
+  render,
+  renderError,
+  toCommandError,
+  parseOutputFlags,
+  isRichUi,
+  displayWidth,
+};

package/engine/cloud-assets/package.cjs

@@ -591,10 +591,14 @@ function cloudRoutingCardProblem(card) {
   if (!workforce || typeof workforce !== "object" || Array.isArray(workforce)) {
     return "workforce must be a complete semantic resume";
   }
+  // `skills` has a floor of 0, not 1. Skills are modules and live outside the
+  // core, so a fully modular agent legitimately declares none. Requiring one
+  // here would block publishing every modular package. Kept identical in
+  // agentlas_desktop/electron/cloud-agents/package.ts — the two must not drift.
   const semanticLists = [
     ["communities", /^community:[a-z0-9][a-z0-9-]*$/, 1, 5],
     ["roles", /^role:[a-z0-9][a-z0-9-]*$/, 0, 4],
-    ["skills", /^skill:[a-z0-9][a-z0-9-]*$/, 1, 12],
+    ["skills", /^skill:[a-z0-9][a-z0-9-]*$/, 0, 12],
     ["knowledge", /^knowledge:[a-z0-9][a-z0-9-]*$/, 0, 256],
   ];
   for (const [field, pattern, minimum, maximum] of semanticLists) {

package/engine/commands/automation.cjs

@@ -2,6 +2,9 @@
 /*
  * automation — 자동화 등록/목록/토글/삭제/실행 (v1 cmdAutomation 의 v2 포팅).
  *   list (기본) | add | on <id> | off <id> | remove <id> | run <id> | runs | daemon
+ *   tick            1회 due 스윕 후 종료(launchd/cron 이 poke 하는 진입점)
+ *   install         macOS launchd 상주 켜기 — 앱/창이 꺼져 있어도 발동(opt-in)
+ *   uninstall       상주 끄기 · status  상주 상태
  *
  * 스케줄 계산은 automation/schedule, DB는 automation/store, 실행은
  * automation/daemon(세션 계층)만 쓴다. run <id> 는 스케줄을 건드리지 않는다
@@ -196,7 +199,40 @@ async function run(ctx, args) {
     return daemon.automationDaemon(ctx, db, { intervalSec: interval, runtimeOverride });
   }
 
-  ctx.err(usage("list|add|on <id>|off <id>|remove <id>|run <id>|runs|daemon"));
+  // 1회 due 스윕 후 종료 — launchd/cron 이 poke 하는 진입점(상주 루프 아님).
+  if (sub === "tick") {
+    await daemon.daemonTick(ctx, db, {});
+    return 0;
+  }
+
+  // 앱/창이 꺼져 있어도 자동화가 발동하도록 macOS launchd 로 상주시킨다(opt-in).
+  if (sub === "install" || sub === "uninstall" || sub === "status") {
+    const launchd = require("../automation/launchd.cjs");
+    if (sub === "status") {
+      const st = launchd.launchdStatus();
+      if (!st.supported) { ctx.out(ko ? "launchd 상주는 macOS 전용입니다. 다른 OS 는 `agentlas automation daemon` 을 켜 두세요." : "launchd persistence is macOS-only. On other systems keep `agentlas automation daemon` running."); return 0; }
+      ctx.out(`${st.loaded ? ctx.ui.green("✓") : ctx.ui.dim("○")} ${ko ? "상주(launchd)" : "persistence (launchd)"}: ${st.loaded ? (ko ? "실행 중" : "loaded") : st.installed ? (ko ? "설치됨(미로드)" : "installed (not loaded)") : (ko ? "미설치" : "not installed")}`);
+      ctx.out(ctx.ui.dim(`plist: ${st.plistPath}`));
+      if (!st.loaded) ctx.out(ctx.ui.dim(ko ? "켜기: agentlas automation install" : "Enable: agentlas automation install"));
+      return 0;
+    }
+    if (sub === "install") {
+      let interval = 300;
+      for (let i = 1; i < args.length; i++) if (args[i] === "--interval") interval = Math.max(30, Number(args[++i]) || 300);
+      const st = launchd.enableLaunchd({ intervalSec: interval });
+      if (st.error) { ctx.err(`${ctx.ui.red("✖")} ${st.error}`); return 1; }
+      ctx.out(`${ctx.ui.green("✓")} ${ko ? "상주를 켰습니다 — 앱/창이 꺼져 있어도 자동화가 발동합니다" : "persistence on — automations fire even with the app/window closed"} (${interval}s)`);
+      ctx.out(ctx.ui.dim(ko ? `${Math.max(30, interval)}초마다 due 를 확인합니다. 끄기: agentlas automation uninstall` : `checks due automations every ${Math.max(30, interval)}s. Disable: agentlas automation uninstall`));
+      return 0;
+    }
+    // uninstall
+    const st = launchd.disableLaunchd();
+    if (st.error) { ctx.err(`${ctx.ui.red("✖")} ${st.error}`); return 1; }
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "상주를 껐습니다. 자동화는 포그라운드 daemon 을 켜 둘 때만 발동합니다." : "persistence off. Automations fire only while a foreground daemon runs."}`);
+    return 0;
+  }
+
+  ctx.err(usage("list|add|on <id>|off <id>|remove <id>|run <id>|runs|daemon|tick|install|uninstall|status"));
   return 1;
 }
 

package/engine/commands/billing.cjs

@@ -25,6 +25,9 @@ function usage(ko) {
     ko
       ? "  구독 계좌(A)와 렌트수익 계좌(B) 잔액을 표시합니다."
       : "  Shows the subscription account (A) and rental-earnings account (B) balances.",
+    ko
+      ? "  크레딧은 Hub 에이전트 호출(공개 에이전트 3·팀 10, 활성 리스는 0)에 쓰입니다."
+      : "  Credits pay for Hub agent calls (public agent 3 · team 10; active leases cost 0).",
     ko
       ? "  참고: 렌트수익(B) → 구독(A) 전송은 Agentlas Desktop 에서만 가능합니다 (터미널 전송 명령 없음)."
       : "  Note: earnings (B) → subscription (A) transfer is Desktop-only (no transfer command in the terminal).",