agentlas 1.0.28 → 1.0.35

package/engine/commands/browser.cjs

@@ -1,19 +1,177 @@
 "use strict";
 /*
- * browser — 실제 브라우저 실행 하드포인트 (hep-browser 라우트).
+ * browser — 실제 브라우저 실행 하드포인트 + 사이트 로그인 볼트·조종 (2026-08-06 확장).
  *
- * v1 디스패처 매핑 그대로:
- *   `agentlas browser <url-or-query|sub…>` → cmdHep(["hep-browser", ...rest])
- *   v1은 browser에 무인자 가드가 없었다(missingArgumentUsage 미포함) —
- *   무인자도 hep-browser 패스스루로 넘어가 네이티브 usage가 나온다. 보존.
+ * 오너 원칙("조종을 다른 흐름으로 확장"): telegram 뿐 아니라 데스크탑의 브라우저-볼트
+ * 흐름(사이트별 전용-프로필 로그인/세션)도 터미널에서 조종·공유되어야 한다. 저장 테이블은
+ * 데스크탑과 공유(browser_sites/…)하고, 조종은 CDP(engine/browser/cdp.cjs)로 한다.
+ *
+ * 하위 명령(볼트·조종):
+ *   browser status                브라우저(Chrome/CDP) 준비 상태 + 사이트 세션 요약
+ *   browser sites                 저장된 사이트와 로그인 세션 상태(valid/expired/none)
+ *   browser add <site> [--label L] [--user U]   사이트 카드 추가(비밀번호 없음)
+ *   browser login <site>          그 사이트를 Agentlas 브라우저로 연다 — 로그인은 사용자가 직접
+ *   browser mark <site> <valid|expired|none>    로그인 뒤 세션 상태를 기록
+ *   browser go <url>              이미 열린 Agentlas 브라우저를 그 URL 로 몬다(조종)
+ *   browser rm <site>             사이트 카드 삭제
+ *
+ * 그 외(무인자 포함, URL·검색어)는 v1 그대로 hep-browser 하드포인트로 넘겨 Chrome 을 띄운다.
+ *
+ * 보안(데스크탑과 동일): 비밀번호를 받지도, 자동 입력하지도 않는다. 로그인은 제공자 페이지에서
+ * 사용자가 직접 한다 — 터미널은 페이지를 열어 주고 세션 상태만 기록한다.
  */
 const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const vault = require("../browser/vault.cjs");
+const cdp = require("../browser/cdp.cjs");
 
-async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("browser", ctx.lang));
+const SUBS = new Set(["status", "sites", "add", "login", "mark", "go", "rm", "remove"]);
+
+function flag(rest, name) {
+  const i = rest.findIndex((a) => a === `--${name}`);
+  return i >= 0 && rest[i + 1] ? rest[i + 1] : null;
+}
+function positional(rest) { return rest.find((a) => a && !String(a).startsWith("-")) || null; }
+
+function siteUrl(site) { return /^[a-z][a-z0-9+.-]*:\/\//i.test(site) ? site : `https://${site}`; }
+
+function statusDot(ui, status) {
+  if (status === "valid") return ui.green("●");
+  if (status === "expired") return ui.yellow ? ui.yellow("●") : ui.dim("●");
+  return ui.dim("○");
+}
+
+async function browserStatus(ctx) {
+  const ko = ctx.lang === "ko";
+  const ready = await cdp.cdpReady();
+  ctx.out(`${ready ? ctx.ui.green("✓") : ctx.ui.dim("○")} ${ko ? "Agentlas 브라우저(CDP)" : "Agentlas browser (CDP)"}: ${ready ? (ko ? "실행 중 — 조종 가능" : "running — pilotable") : (ko ? "꺼짐" : "not running")} (port ${cdp.DEFAULT_PORT})`);
+  const sites = vault.listBrowserSites(ctx.db());
+  if (!sites.length) {
+    ctx.out(ctx.ui.dim(ko ? "저장된 사이트 없음. 추가: agentlas browser add <site>" : "No saved sites. Add one: agentlas browser add <site>"));
+    return 0;
+  }
+  const valid = sites.filter((s) => s.session.status === "valid").length;
+  ctx.out(ctx.ui.dim(ko ? `사이트 ${sites.length}개 (로그인 유효 ${valid}개) — 목록: agentlas browser sites` : `${sites.length} sites (${valid} logged in) — list: agentlas browser sites`));
+  return 0;
+}
+
+function browserSites(ctx) {
+  const ko = ctx.lang === "ko";
+  const sites = vault.listBrowserSites(ctx.db());
+  if (!sites.length) {
+    ctx.out(ctx.ui.dim(ko ? "저장된 사이트가 없습니다. 추가: agentlas browser add <site>" : "No saved sites yet. Add one: agentlas browser add <site>"));
     return 0;
   }
+  for (const s of sites) {
+    const when = s.session.capturedAt ? new Date(s.session.capturedAt).toLocaleDateString() : "";
+    const label = s.label ? ` ${ctx.ui.dim(s.label)}` : "";
+    const user = s.username ? ctx.ui.dim(` (${s.username})`) : "";
+    ctx.out(`${statusDot(ctx.ui, s.session.status)} ${s.site}${label}${user}  ${ctx.ui.dim(`${s.session.status}${when ? " · " + when : ""}`)}`);
+  }
+  return 0;
+}
+
+function browserAdd(ctx, rest) {
+  const ko = ctx.lang === "ko";
+  const site = positional(rest);
+  if (!site) { ctx.err(ko ? "사용법: agentlas browser add <site> [--label 이름] [--user 아이디]" : "Usage: agentlas browser add <site> [--label name] [--user handle]"); return 1; }
+  try {
+    const row = vault.upsertBrowserSite(ctx.db(), { site, label: flag(rest, "label"), username: flag(rest, "user") });
+    vault.logBrowserAction(ctx.db(), { site: row.site, action: "vault.save", result: "ok" });
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "사이트를 저장했습니다" : "site saved"}: ${row.site}`);
+    ctx.out(ctx.ui.dim(ko ? `로그인: agentlas browser login ${row.site}` : `Log in: agentlas browser login ${row.site}`));
+    return 0;
+  } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+}
+
+async function browserLogin(ctx, rest) {
+  const ko = ctx.lang === "ko";
+  const site = positional(rest);
+  if (!site) { ctx.err(ko ? "사용법: agentlas browser login <site>" : "Usage: agentlas browser login <site>"); return 1; }
+  const db = ctx.db();
+  let row;
+  try { row = vault.upsertBrowserSite(db, { site }); } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+  const url = siteUrl(row.site);
+
+  if (await cdp.cdpReady()) {
+    // 이미 열린 Agentlas 브라우저를 로그인 페이지로 몬다(조종). 로그인은 사용자가 직접.
+    try {
+      const page = await cdp.attachPage();
+      try { await page.navigate(url, { waitMs: 1500 }); } finally { page.close(); }
+      vault.logBrowserAction(db, { site: row.site, action: "login.open", target: url, result: "navigated" });
+      ctx.out(`${ctx.ui.green("✓")} ${ko ? "브라우저를 로그인 페이지로 옮겼습니다" : "moved the browser to the login page"}: ${url}`);
+    } catch (e) {
+      ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+      return 1;
+    }
+  } else {
+    // CDP 미기동 — 조종할 대상이 없다. 먼저 브라우저를 띄우도록 정직하게 안내(자동 실행 안 함).
+    ctx.out(ko
+      ? `Agentlas 브라우저가 아직 실행 중이 아닙니다. 먼저 열어 주세요:\n  agentlas browser ${url}`
+      : `The Agentlas browser is not running yet. Open it first:\n  agentlas browser ${url}`);
+  }
+  ctx.out(ctx.ui.dim(ko
+    ? `그 창에서 직접 로그인한 뒤, 세션을 기록하세요:\n  agentlas browser mark ${row.site} valid`
+    : `Log in yourself in that window, then record the session:\n  agentlas browser mark ${row.site} valid`));
+  ctx.out(ctx.ui.dim(ko ? "비밀번호는 받지도, 자동 입력하지도 않습니다 — 로그인은 사용자만." : "No password is ever taken or auto-typed — you log in, not the tool."));
+  return 0;
+}
+
+function browserMark(ctx, rest) {
+  const ko = ctx.lang === "ko";
+  const site = positional(rest);
+  const status = rest.filter((a) => a && !String(a).startsWith("-") && a !== site)[0];
+  if (!site || !status) { ctx.err(ko ? "사용법: agentlas browser mark <site> <valid|expired|none>" : "Usage: agentlas browser mark <site> <valid|expired|none>"); return 1; }
+  try {
+    const row = vault.setBrowserSession(ctx.db(), site, status);
+    vault.logBrowserAction(ctx.db(), { site: row.site, action: "session.mark", result: status });
+    ctx.out(`${ctx.ui.green("✓")} ${row.site}: ${ko ? "세션 상태" : "session"} → ${status}`);
+    return 0;
+  } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+}
+
+async function browserGo(ctx, rest) {
+  const ko = ctx.lang === "ko";
+  const url = positional(rest);
+  if (!url) { ctx.err(ko ? "사용법: agentlas browser go <url>" : "Usage: agentlas browser go <url>"); return 1; }
+  if (!(await cdp.cdpReady())) {
+    ctx.err(ko
+      ? `Agentlas 브라우저가 실행 중이 아닙니다. 먼저 열어 주세요: agentlas browser ${siteUrl(url)}`
+      : `The Agentlas browser is not running. Open it first: agentlas browser ${siteUrl(url)}`);
+    return 1;
+  }
+  try {
+    const page = await cdp.attachPage();
+    let title;
+    try { await page.navigate(siteUrl(url), { waitMs: 1500 }); title = await page.evalExpr("document.title"); } finally { page.close(); }
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "이동했습니다" : "navigated"}: ${siteUrl(url)}${title ? ctx.ui.dim(` — ${title}`) : ""}`);
+    return 0;
+  } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+}
+
+function browserRemove(ctx, rest) {
+  const ko = ctx.lang === "ko";
+  const site = positional(rest);
+  if (!site) { ctx.err(ko ? "사용법: agentlas browser rm <site>" : "Usage: agentlas browser rm <site>"); return 1; }
+  vault.deleteBrowserSite(ctx.db(), site);
+  vault.logBrowserAction(ctx.db(), { site: vault.normalizeSite(site), action: "vault.delete", result: "ok" });
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "사이트를 삭제했습니다" : "site removed"}: ${vault.normalizeSite(site) || site}`);
+  return 0;
+}
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) { ctx.out(usageFor("browser", ctx.lang)); return 0; }
+  const sub = String(args[0] || "").toLowerCase();
+  const rest = args.slice(1);
+  if (SUBS.has(sub)) {
+    if (sub === "status") return browserStatus(ctx);
+    if (sub === "sites") return browserSites(ctx);
+    if (sub === "add") return browserAdd(ctx, rest);
+    if (sub === "login") return browserLogin(ctx, rest);
+    if (sub === "mark") return browserMark(ctx, rest);
+    if (sub === "go") return browserGo(ctx, rest);
+    if (sub === "rm" || sub === "remove") return browserRemove(ctx, rest);
+  }
+  // 그 외(무인자·URL·검색어)는 v1 그대로 hep-browser 하드포인트로 — Chrome 을 실제로 띄운다.
   return create(ctx).cmdHep(["hep-browser", ...args]);
 }
 

package/engine/commands/build.cjs

@@ -1,33 +1,114 @@
 "use strict";
 /*
- * build — 에이전트/팀 빌드·수리·패키징 (hep-build 라우트).
+ * build — 에이전트를 로컬에서 빌드·설치한다 (독립, 2026-08-06 재작성).
  *
- * v1 디스패처 검증 메모 (legacy-v1-engine-snapshot engine/agentlas.cjs ~13097):
- *   v1의 `agentlas build`는 hep-build 단순 패스스루가 아니라 터미널 소유
- *   빌더(terminalAssets.cmdBuild: 시스템 MCP 메타데이터 프리플라이트 → 1회
- *   동의 → Meta-Agent 실행)로 갔다. 그 프리플라이트/빌더 체인은 engine/mcp/*
- *   와 빌더 서브시스템 소유라 이 클러스터의 범위 밖이다.
- *   v2의 이 파일은 v1 도움말이 계약으로 명시한 표면 —
- *   `build "<request>" … (hep-build)` — 즉 Agentlas OS hep-build 라우트를
- *   그대로 노출한다. 터미널 소유 MCP-동의 빌더가 v2에 재구축되면 그 모듈이
- *   이 명령을 대체(또는 선행)해야 한다.
+ * 이전: `build "<req>"`는 Hephaestus 네이티브 hep-build 패스스루였고, 그 네이티브는
+ * "Open Claude Code or Codex with the plugin, then /hep-build"라는 스텁만 냈다 —
+ * 플러그인을 강제해 오너 원칙(데스크탑/플러그인은 공유하되 전제 아님)을 어겼다.
  *
- * v1 인자 가드 그대로:
- *   - help 토큰 → usage 출력, exit 0
- *   - 무인자   → usage 실패, exit 1 (요청 문자열이 라우터로 새는 것 방지)
+ * 지금: 터미널 자체 런타임으로 로컬 빌더(agents/builder.cjs)를 `run`과 같은
+ * 실행 인프라(Orchestrator 세션)로 돌려 import 가능한 폴더를 만들고, 성공하면
+ * 자동 설치한다. 폴더는 남으므로 자동 설치가 실패해도 `agentlas import`로 복구 가능.
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { Orchestrator } = require("../sessions/orchestrator.cjs");
+const { Renderer } = require("../ui/renderer.cjs");
+const { resolveRuntimeForAgent } = require("../runtimes/overrides.cjs");
+const permissions = require("../agentlas-permissions.cjs");
+const { projectCwd } = require("../project/paths.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
+const { ensureBuilderAgent, parseBuiltFolder } = require("../agents/builder.cjs");
+const { importLocalFolder } = require("../agents/import-local.cjs");
+const path = require("node:path");
+const fs = require("node:fs");
+
+function usage(ko) {
+  return ko
+    ? "사용법: agentlas build \"<만들고 싶은 에이전트>\"  [--runtime <kind>] [--print]"
+    : "Usage: agentlas build \"<the agent you want>\"  [--runtime <kind>] [--print]";
+}
 
 async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("build", ctx.lang));
-    return 0;
+  const ko = ctx.lang === "ko";
+  if (args.some((a) => a === "--help" || a === "-h" || a === "help")) { ctx.out(usage(ko)); return 0; }
+
+  // --runtime/--print 만 벗겨내고 나머지는 요청 문장.
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--runtime" && args[i + 1]) { flags.runtime = args[++i]; continue; }
+    if (args[i] === "--print" || args[i] === "-p") { flags.print = true; continue; }
+    rest.push(args[i]);
+  }
+  const request = rest.join(" ").trim();
+  if (!request) { ctx.err("✖ " + usage(ko)); return 1; }
+
+  const db = ctx.db();
+  const cwd = projectCwd();
+  const agent = ensureBuilderAgent(db);
+
+  let runtime;
+  try {
+    runtime = resolveRuntimeForAgent({
+      db, prefs: ctx.prefs, explicit: flags.runtime, role: "orchestrator", agentId: agent.id,
+    });
+  } catch (e) {
+    // no_runtime 등 정직 정지 그대로.
+    ctx.err(String((e && e.message) || e));
+    return 1;
+  }
+
+  // 빌더는 파일을 써야 한다 — write 권한으로 실행한다(현재 폴더에 패키지 생성).
+  const permission = permissions.normalize("write");
+  try { ensureTerminalProjectForExecutionCli(db, cwd, permission, "terminal-build"); } catch { /* 프로젝트 없어도 빌드는 됨 */ }
+
+  const orch = new Orchestrator({ db, lang: ctx.lang });
+  const session = orch.spawn({ agent, runtime, permission, cwd, title: `build: ${request.slice(0, 48)}` });
+
+  let renderer = null;
+  if (!flags.print) {
+    renderer = new Renderer(ctx.uiInstance);
+    renderer.attach(session, { replay: false });
+    ctx.err(ctx.uiInstance.c.dim(`${agent.slug} · ${runtime.kind}${runtime.model ? ` · ${runtime.model}` : ""}`));
   }
-  if (!args.length) {
-    ctx.err("✖ " + usageFor("build", ctx.lang));
+
+  const res = await session.send(request);
+  if (renderer) renderer.detach();
+  const finalText = (res && (res.finalText || res.text)) || "";
+  if (flags.print && finalText) process.stdout.write(finalText.trimEnd() + "\n");
+
+  if (session.status === "failed") {
+    if (session.lastError) ctx.err(session.lastError);
     return 1;
   }
-  return create(ctx).cmdHep(["hep-build", ...args]);
+
+  // 빌더가 `BUILT: <folder>`를 남겼으면 자동 설치한다.
+  const built = parseBuiltFolder(finalText);
+  if (!built) {
+    ctx.out(ctx.uiInstance.c.dim(ko
+      ? "빌드 산출물 위치를 확정하지 못했습니다. 만들어진 폴더를 확인해 `agentlas import <폴더>`로 설치하세요."
+      : "Could not confirm the built folder. Check the created folder and install it with `agentlas import <folder>`."));
+    return 0;
+  }
+  const builtPath = path.isAbsolute(built) ? built : path.join(cwd, built);
+  if (!fs.existsSync(builtPath)) {
+    ctx.out(ctx.uiInstance.c.dim(ko
+      ? `빌더가 알린 폴더가 없습니다: ${built}. 만들어진 폴더를 확인해 \`agentlas import\`로 설치하세요.`
+      : `The reported folder does not exist: ${built}. Check the created folder and install it with \`agentlas import\`.`));
+    return 0;
+  }
+  try {
+    const imported = importLocalFolder(db, builtPath);
+    ctx.out(`${ctx.uiInstance.c.green("✓")} ${ko ? "설치됨" : "installed"}: ${imported.slug} — ${imported.name}`);
+    ctx.out(ctx.uiInstance.c.dim(ko
+      ? `실행: agentlas run ${imported.slug} "<할 일>"`
+      : `Run it: agentlas run ${imported.slug} "<task>"`));
+    return 0;
+  } catch (e) {
+    ctx.out(ctx.uiInstance.c.dim(ko
+      ? `자동 설치 실패(${String((e && e.message) || e)}). 폴더는 남아 있습니다: ${builtPath}. \`agentlas import ${builtPath}\`로 설치하세요.`
+      : `Auto-install failed (${String((e && e.message) || e)}). The folder remains at ${builtPath}. Install with \`agentlas import ${builtPath}\`.`));
+    return 0;
+  }
 }
 
 module.exports = { run };

package/engine/commands/connect.cjs

@@ -1,20 +1,173 @@
 "use strict";
 /*
- * connect — Telegram 등 플랫폼 연결 (hep-connect 라우트).
+ * connect — Telegram 연결·조종 (2026-08-06 독립화).
  *
- * v1 디스패처 매핑 그대로:
- *   `agentlas connect <sub…>` → cmdHep(["hep-connect", ...rest])
- *   무인자 connect는 v1에서 fail이 아니라 usage 안내 후 exit 0이었다
- *   (topLevelCommandUsage("connect") 특례) — 그대로 보존.
+ * 오너 원칙: 데스크탑에서 쉽게 되는 telegram 연결이 터미널에서도 돼야 한다.
+ * 데스크탑 electron/telegram/connect.ts 의 실제 연결 코어는 순수 HTTPS
+ * (api.telegram.org)이고 Electron 이 필요 없다 — 브라우저 자동 조종은 봇 자동
+ * 생성 편의일 뿐. 그 코어를 engine/telegram/connect.cjs 로 이식했다. 여기서는
+ * CLI 표면만 배선한다.
+ *
+ * 이전: connect 는 hep-connect 플러그인 패스스루라 라우터 원시 JSON 을 덤프했다.
+ *
+ * 하위 명령:
+ *   connect                           상태 표
+ *   connect telegram <agent|firm>     이 대상에 봇을 연결(토큰 stdin) + 방 페어링
+ *   connect test <id>                 연결된 방에 확인 메시지
+ *   connect remove <id>               연결 제거(토큰 파일도 삭제)
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { renderTelegram } = require("./telegram.cjs");
+const tg = require("../telegram/connect.cjs");
+const { findAgent } = require("../agents/registry.cjs");
+const readline = require("node:readline");
+
+function usage(ko) {
+  return ko
+    ? "사용법: agentlas connect [ status | telegram <agent|firm> [--auto] | test <id> | remove <id> ]"
+    : "Usage: agentlas connect [ status | telegram <agent|firm> [--auto] | test <id> | remove <id> ]";
+}
+
+function resolveTarget(db, token) {
+  const agent = findAgent(db, token);
+  if (agent) return { kind: "agent", id: agent.id, name: agent.name || agent.slug };
+  try {
+    const q = String(token).trim().toLowerCase();
+    const firm = db.prepare("SELECT id, slug, name FROM firms WHERE lower(id)=? OR lower(slug)=? OR lower(name)=?").get(q, q, q)
+      || db.prepare("SELECT id, slug, name FROM firms WHERE lower(slug) LIKE ? ORDER BY slug LIMIT 1").get(`%${q}%`);
+    if (firm) return { kind: "firm", id: firm.id, name: firm.name || firm.slug };
+  } catch { /* no firms table */ }
+  return null;
+}
+
+/** 봇 토큰을 stdin 에서 읽는다(비밀은 argv 금지). 파이프면 첫 줄, TTY면 숨김 안내. */
+async function readTokenFromStdin(ctx, ko) {
+  if (!process.stdin.isTTY) {
+    return new Promise((resolve) => {
+      let buf = "";
+      process.stdin.on("data", (d) => { buf += d; });
+      process.stdin.on("end", () => resolve(buf.split(/\r?\n/)[0].trim()));
+    });
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  ctx.out(ko
+    ? "@BotFather 에서 봇을 만들고 받은 토큰을 붙여넣으세요 (입력은 화면에 남습니다 — 끝나면 창을 지우세요):"
+    : "Create a bot with @BotFather and paste the token (it echoes — clear your screen after):");
+  return new Promise((resolve) => {
+    rl.question("token> ", (answer) => { rl.close(); resolve(String(answer).trim()); });
+  });
+}
+
+async function connectTelegram(ctx, targetToken, { auto = false } = {}) {
+  const ko = ctx.lang === "ko";
+  const db = ctx.db();
+  const target = resolveTarget(db, targetToken);
+  if (!target) {
+    ctx.err((ko ? "대상을 찾을 수 없습니다: " : "target not found: ") + targetToken);
+    ctx.err(ctx.ui.dim(ko ? "에이전트·회사 목록: agentlas list" : "list agents and companies: agentlas list"));
+    return 1;
+  }
+
+  let token;
+  if (auto) {
+    // --auto: 터미널이 Agentlas 브라우저(CDP)로 BotFather 를 열고 토큰을 직접 읽는다.
+    ctx.out(ko
+      ? "Agentlas 브라우저에서 BotFather 를 엽니다. 필요하면 로그인(QR)한 뒤, `/newbot` 으로 봇을 만드세요 — 토큰은 제가 화면에서 읽어옵니다."
+      : "Opening BotFather in the Agentlas browser. Log in (QR) if needed, then create a bot with `/newbot` — I'll read the token off the page.");
+    try {
+      if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "BotFather 토큰 대기 중…" : "Waiting for a BotFather token…");
+      token = await require("../telegram/connect.cjs").captureBotTokenViaBrowser({ timeoutMs: 180_000 });
+    } catch (e) {
+      if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+      if (e && e.code === "cdp_unavailable") {
+        ctx.err(ko
+          ? "Agentlas 브라우저가 실행 중이 아닙니다. 먼저 `agentlas browser https://web.telegram.org` 로 브라우저를 띄운 뒤 다시 --auto 하거나, --auto 없이 토큰을 직접 붙여넣으세요."
+          : "The Agentlas browser is not running. Start it with `agentlas browser https://web.telegram.org`, then retry --auto, or paste the token without --auto.");
+        return 1;
+      }
+      ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+      return 1;
+    }
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    if (!token) {
+      ctx.err(ko ? "시간 내 토큰을 못 읽었습니다(3분). 다시 시도하거나 --auto 없이 붙여넣으세요." : "No token captured in time (3 min). Retry, or paste it without --auto.");
+      return 1;
+    }
+    ctx.out(ctx.ui.dim(ko ? "토큰을 읽었습니다." : "Captured the token."));
+  } else {
+    token = await readTokenFromStdin(ctx, ko);
+    if (!token) { ctx.err(ko ? "토큰이 필요합니다." : "a bot token is required."); return 1; }
+  }
+
+  let started;
+  try {
+    if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "봇 토큰 확인 중…" : "Verifying bot token…");
+    started = await tg.startConnection(db, target.kind, target.id, token);
+  } catch (e) {
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+    return 1;
+  }
+  if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+  const botAt = started.botUsername ? "@" + started.botUsername : "(bot)";
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "봇 확인됨" : "bot verified"}: ${botAt} → ${target.name}`);
+  ctx.out(ko
+    ? `이제 텔레그램에서 ${botAt} 에게 아무 메시지나 보내세요 (예: /start). 방을 기다립니다…`
+    : `Now message ${botAt} on Telegram (e.g. /start). Waiting for the chat…`);
+
+  let paired;
+  try {
+    if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "방 연결 대기 중…" : "Waiting for the chat…");
+    paired = await tg.pairByPolling(db, started.id, { timeoutMs: 120_000 });
+  } catch (e) {
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+    return 1;
+  }
+  if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+
+  if (!paired) {
+    ctx.out(ctx.ui.dim(ko
+      ? `방을 못 받았습니다(2분 초과). ${botAt} 에게 메시지를 보낸 뒤 다시: agentlas connect test ${started.id}`
+      : `No chat received (2 min). Message ${botAt}, then retry: agentlas connect test ${started.id}`));
+    return 0;
+  }
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "방 연결됨" : "chat paired"}: ${paired.telegram_chat_title || paired.telegram_chat_id}`);
+  try {
+    await tg.sendTest(db, started.id, ko ? `Agentlas 연결 완료 — ${target.name}` : `Agentlas connected — ${target.name}`);
+    ctx.out(ctx.ui.dim(ko ? "확인 메시지를 보냈습니다." : "Sent a confirmation message."));
+  } catch { /* 페어링은 됐으니 테스트 실패는 치명적 아님 */ }
+  return 0;
+}
 
 async function run(ctx, args) {
-  if (args.some(isHelpToken) || !args.length) {
-    ctx.out(usageFor("connect", ctx.lang));
+  const ko = ctx.lang === "ko";
+  const sub = String(args[0] || "").toLowerCase();
+
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") { ctx.out(usage(ko)); return 0; }
+  if (sub === "status") return renderTelegram(ctx);
+  if (sub === "telegram") {
+    const rest = args.slice(1);
+    const auto = rest.includes("--auto");
+    const targetToken = rest.find((a) => a && !String(a).startsWith("-"));
+    if (!targetToken) { ctx.err(usage(ko)); return 1; }
+    return connectTelegram(ctx, targetToken, { auto });
+  }
+  if (sub === "test") {
+    if (!args[1]) { ctx.err(ko ? "사용법: agentlas connect test <id>" : "Usage: agentlas connect test <id>"); return 1; }
+    try {
+      await tg.sendTest(ctx.db(), args[1], ko ? "Agentlas 테스트 메시지" : "Agentlas test message");
+      ctx.out(`${ctx.ui.green("✓")} ${ko ? "메시지를 보냈습니다." : "message sent."}`);
+      return 0;
+    } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+  }
+  if (sub === "remove") {
+    if (!args[1]) { ctx.err(ko ? "사용법: agentlas connect remove <id>" : "Usage: agentlas connect remove <id>"); return 1; }
+    tg.removeBinding(ctx.db(), args[1]);
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "연결을 제거했습니다." : "connection removed."}`);
     return 0;
   }
-  return create(ctx).cmdHep(["hep-connect", ...args]);
+  ctx.err(usage(ko));
+  return 1;
 }
 
 module.exports = { run };

package/engine/commands/creds.cjs

@@ -134,17 +134,79 @@ async function cmdCredsFile(ctx, args) {
   return 0;
 }
 
+/** KEY=value 파일에서 KEY 이름만 뽑는다 — 값은 절대 읽어 돌려주지 않는다. */
+function envKeyNames(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8")
+      .split(/\r?\n/)
+      .map((line) => line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/))
+      .filter(Boolean)
+      .map((m) => m[1]);
+  } catch {
+    return null; // 파일 없음/읽기 불가 — 목록에서 침묵이 아니라 부재로 표시
+  }
+}
+
+/*
+ * creds list — 어떤 자격증명 "이름"이 어디에 저장돼 있는지.
+ * 배경(2026-08-05 감사, 결함 H): save/file만 있어 저장한 것을 확인할 방법이
+ * 없었다. 계약은 상단과 동일 — 값은 어떤 경로로도 출력하지 않는다. 키 이름과
+ * 저장 위치까지만. (키체인 vault는 standalone에서 keytar를 부르면 무한 대기하는
+ * v1 실사고가 있어 조회조차 하지 않는다 — 부재가 아니라 "미조회"로 표시.)
+ */
+function cmdCredsList(ctx) {
+  const ko = ctx.lang !== "en";
+  const project = activeProjectPath(ctx.db());
+  const stores = [];
+  if (project) stores.push({ label: (ko ? "프로젝트 .env — " : "project .env — ") + path.join(project, ".env"), keys: envKeyNames(path.join(project, ".env")) });
+  stores.push({ label: (ko ? "전역 credentials.env — " : "global credentials.env — ") + path.join(userDataDir(), "credentials.env"), keys: envKeyNames(path.join(userDataDir(), "credentials.env")) });
+  stores.push({ label: "~/.agentlas/credentials.env", keys: envKeyNames(path.join(os.homedir(), ".agentlas", "credentials.env")) });
+
+  let any = false;
+  for (const store of stores) {
+    if (store.keys === null) continue; // 파일 자체가 없으면 줄을 만들지 않는다
+    any = true;
+    ctx.out(ctx.ui.bold(store.label));
+    if (!store.keys.length) ctx.out(ctx.ui.dim(ko ? "  (비어 있음)" : "  (empty)"));
+    for (const key of store.keys) ctx.out(`  ${key}${ctx.ui.dim("=•••")}`);
+  }
+  if (isElectronRuntime()) {
+    ctx.out(ctx.ui.dim(ko ? "키체인 vault: 데스크탑에서 확인" : "keychain vault: inspect in Desktop"));
+  } else {
+    ctx.out(ctx.ui.dim(ko
+      ? "키체인 vault는 standalone 터미널에서 조회하지 않습니다(서명 없는 keytar 호출은 키체인에 막혀 멈춥니다)."
+      : "The keychain vault is not queried from the standalone terminal (unsigned keytar calls hang on the OS keychain)."));
+  }
+  if (!any) ctx.out(ko ? "저장된 자격증명 파일이 없습니다. agentlas creds save 로 추가하세요." : "No credential files yet. Add one with: agentlas creds save");
+  return 0;
+}
+
 async function run(ctx, args) {
   const fail = (msg) => { ctx.err(msg); return 1; };
   const sub = args[0];
   if (sub === "file") return cmdCredsFile(ctx, args.slice(1));
+  if (sub === "list" || sub === "ls") return cmdCredsList(ctx);
   if (sub !== "save") {
-    return fail('usage: agentlas creds save --provider <name> --key <ENV_NAME> --value <value> [--project <path>] OR agentlas creds file --source <path> [--env <ENV_NAME>]');
+    return fail('usage: agentlas creds save --provider <name> --key <ENV_NAME> --value <value> [--project <path>] OR agentlas creds file --source <path> [--env <ENV_NAME>] OR agentlas creds list');
   }
   const f = parseCredFlags(args.slice(1));
   const key = typeof f.key === "string" ? f.key.trim() : "";
-  const value = f.value === undefined || f.value === true ? "" : String(f.value);
-  if (!key || !value) return fail("creds save requires --key and --value");
+  let value = f.value === undefined || f.value === true ? "" : String(f.value);
+  /*
+   * 비밀은 argv에 실리면 안 된다(clig.dev: never read secrets from flags) —
+   * 셸 히스토리와 `ps` 출력에 평문으로 남는다. `--value -` 는 stdin에서 읽는다:
+   *   printf '%s' "$SECRET" | agentlas creds save --key X --value -
+   * argv로 직접 준 경우는 기존 사용을 깨지 않되, 노출 사실을 그 자리에서 알린다.
+   */
+  if (value === "-") {
+    value = fs.readFileSync(0, "utf8").replace(/\r?\n$/, "");
+    if (!value) return fail("creds save --value - expected the secret on stdin, but stdin was empty");
+  } else if (value) {
+    ctx.err(ctx.lang === "ko"
+      ? "참고: --value 로 준 비밀은 셸 히스토리·ps 에 남습니다. 다음부터는 stdin 을 쓰세요: printf '%s' \"$SECRET\" | agentlas creds save --key X --value -"
+      : "Note: a secret passed via --value lands in shell history and `ps`. Prefer stdin next time: printf '%s' \"$SECRET\" | agentlas creds save --key X --value -");
+  }
+  if (!key || !value) return fail("creds save requires --key and --value (use `--value -` to read the secret from stdin)");
   const provider = typeof f.provider === "string" && f.provider ? f.provider : key;
   const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
   const targets = [];