agentlas 1.0.28 → 1.0.35

package/engine/project/team.cjs

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * project/team — 터미널에서 프로젝트를 만들고 순서 팀을 편성한다 (독립).
+ *
+ * 배경(2026-08-06, 오너 원칙): 데스크탑/플러그인은 산출물·설정을 **공유**할 뿐,
+ * 설치되어 있거나 거기서 작업이 선행되어야 하는 것은 아니다. 그런데 projects
+ * 행을 쓰는 곳이 터미널 엔진에 0곳이라, `run "<task>"`가 "Desktop Work에서
+ * 연결하세요"로 막혔다 — 데스크탑을 강제하는 격차. 스키마(projects)는 터미널이
+ * 부트스트랩하는 공유 스키마이므로, 여기서 직접 쓴다.
+ *
+ * 계약(데스크탑 tasks.createProject와 동형):
+ *  - 순서 팀의 index 0(컨트롤러)은 로컬 설치 에이전트여야 한다. 로컬이 아니면
+ *    폰이 프로젝트를 시작 불가로 만들 수 있다는 모바일 계약과 같은 이유 —
+ *    컨트롤러는 이 머신에서 반드시 실행 가능해야 한다.
+ *  - 풀 멤버 형태는 controller.cjs parseAgentPool과 정확히 일치:
+ *    { agentId, source, releaseId, nameSnapshot }.
+ *  - 폴더당 프로젝트는 하나로 수렴한다. 같은 folder_path가 이미 있으면 그 행을
+ *    갱신하고, 없으면 만든다(데스크탑이 만든 프로젝트도 그대로 이어받는다).
+ */
+const crypto = require("node:crypto");
+const path = require("node:path");
+const fs = require("node:fs");
+const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
+const { findAgent } = require("../agents/registry.cjs");
+
+function canonical(p) {
+  const resolved = path.resolve(String(p || ""));
+  try { return fs.realpathSync.native(resolved); } catch { return resolved; }
+}
+
+/** slug/이름 목록 → 검증된 순서 풀. 못 찾은 이름은 정직하게 실패. */
+function resolveTeam(db, tokens) {
+  const pool = [];
+  for (const token of tokens) {
+    const agent = findAgent(db, token);
+    if (!agent) {
+      throw Object.assign(new Error(`agent not found: ${token}`), { code: "team_agent_not_found", honestStop: true, token });
+    }
+    // 설치 에이전트는 로컬이다(installed_agents에 있음 = 이 머신에서 실행 가능).
+    pool.push({
+      agentId: agent.id,
+      source: "local",
+      releaseId: null,
+      nameSnapshot: agent.name || agent.slug || agent.id,
+    });
+  }
+  return pool;
+}
+
+/**
+ * connectProjectTeam(db, folder, tokens, opts)
+ *   folder: 프로젝트 루트(cwd)
+ *   tokens: 순서 팀 slug/이름 배열 (index 0 = 컨트롤러)
+ *   opts.name / opts.systemPrompt (선택)
+ * → { id, name, folderPath, team: [{agentId, nameSnapshot}], created }
+ */
+function connectProjectTeam(db, folder, tokens, opts = {}) {
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    throw Object.assign(new Error("a project team needs at least one agent (the first is the controller)"), { code: "team_empty", honestStop: true });
+  }
+  const columns = new Set(db.prepare("PRAGMA table_info(projects)").all().map((r) => r.name));
+  if (!columns.has("folder_path") || !columns.has("agent_pool_json")) {
+    throw Object.assign(new Error("This Agentlas data store does not support project teams yet."), { code: "project_teams_unsupported", honestStop: true });
+  }
+  const team = resolveTeam(db, tokens);
+  const root = canonical(folder);
+  const now = new Date().toISOString();
+  const poolJson = JSON.stringify(team);
+  const controllerId = team[0].agentId;
+  // default_agent_id 는 데스크탑 마이그레이션이 추가한 컬럼이라 터미널이 신선
+  // 부트스트랩한 스키마엔 없을 수 있다 — 있을 때만 쓴다. 컨트롤러 정본은 늘
+  // agent_pool_json[0]다(default_agent_id는 데스크탑 호환용 보조 필드).
+  const hasDefaultCol = columns.has("default_agent_id");
+
+  return runWriteTransaction(db, () => {
+    // 같은 폴더의 기존 프로젝트를 찾는다(데스크탑이 만든 것 포함, 정확 경로만).
+    const existing = db.prepare(
+      "SELECT id, name FROM projects WHERE folder_path IS NOT NULL AND folder_path = ?",
+    ).get(root) || null;
+    if (existing) {
+      const sets = ["agent_pool_json=?", "updated_at=?"];
+      const vals = [poolJson, now];
+      if (hasDefaultCol) { sets.push("default_agent_id=?"); vals.push(controllerId); }
+      if (opts.name) { sets.push("name=?"); vals.push(opts.name); }
+      if (opts.systemPrompt !== undefined) { sets.push("system_prompt=?"); vals.push(opts.systemPrompt); }
+      db.prepare(`UPDATE projects SET ${sets.join(", ")} WHERE id=?`).run(...vals, existing.id);
+      return { id: existing.id, name: opts.name || existing.name, folderPath: root, team, created: false };
+    }
+    const id = `project:local:${crypto.randomUUID()}`;
+    const name = opts.name || path.basename(root) || "Project";
+    const cols = ["id", "name", "description", "system_prompt", "agent_pool_json", "source_type", "source_ref", "created_at", "updated_at", "folder_path"];
+    const vals = [id, name, null, opts.systemPrompt ?? null, poolJson, "local", null, now, now, root];
+    if (hasDefaultCol) { cols.splice(3, 0, "default_agent_id"); vals.splice(3, 0, controllerId); }
+    db.prepare(`INSERT INTO projects (${cols.join(", ")}) VALUES (${cols.map(() => "?").join(",")})`).run(...vals);
+    return { id, name, folderPath: root, team, created: true };
+  });
+}
+
+module.exports = { connectProjectTeam, resolveTeam };

package/engine/runtime-refusal.cjs

@@ -0,0 +1,71 @@
+/**
+ * 런타임 거절 고지문 판별 — **표식이 없는 런타임을 위한 최후 수단, 이 저장소에서 이 파일 하나뿐.**
+ *
+ * 원칙(2026-08-06 실측 사고에서): 실패 판정은 런타임의 기계 표식(res.error / errorKind)으로
+ * 한다. 텍스트 모양을 보는 것은 표식을 아예 안 주는 케이스(실측: codex 한도 — 거절문이
+ * agent_message로 오고 turn.completed, 표식 0)에서만 허용되고, 그 판별 로직은 여기 한 곳에만
+ * 산다. 흩어지면 조율 불가능한 키워드 그물이 여러 벌 생긴다.
+ *
+ * 오탐 방어(이게 이 모듈의 존재 이유다):
+ *  - 전체 출력이 짧을 때만(고지문은 한두 문장이다 — 긴 답 속의 "429" 언급은 산출물).
+ *  - 구조(JSON·다문단)가 보이면 산출물로 간주.
+ *  - 앵커된 고지 문구만("You've hit", "usage limit" …) — 낱말 하나로 판정하지 않는다.
+ *  - 판별 결과는 항상 heuristic 출처로 표기해야 한다 — 화면은 단정 대신 완곡하게 말하고,
+ *    원문은 저널에 보존한다.
+ *
+ * 쌍둥이: agentlas_desktop/electron/runtime/runtime-refusal.ts (수동 동기 — 런타임 계층은
+ * 미러 코드가 아니라 패리티 게이트가 없다. 규칙을 바꾸면 양쪽을 같이 바꿀 것.)
+ */
+"use strict";
+
+const MAX_NOTICE_LENGTH = 400;
+
+/**
+ * 앵커된 고지 문구 — "거절을 사람에게 알리는 문장"의 형태.
+ * 낱말(limit, quota)이 아니라 구절이다. 여기 추가할 때는 실측 원문을 근거로.
+ */
+const NOTICE_PATTERNS = [
+  /\byou'?ve hit\b/i,                 // "You've hit your weekly/usage limit" (claude·codex 실측)
+  /\busage limit\b/i,
+  /\brate.?limit(ed)?\b/i,
+  /\bquota (exceeded|reached)\b/i,
+  /\bresets? (at|on)\b/i,             // "resets Aug 8 at 6pm"
+  /\btry again (at|later)\b/i,
+  /\bupgrade to\b/i,                  // "Upgrade to Pro" (codex 실측)
+  /\bpurchase more credits\b/i,
+  /\bout of credits\b/i,
+  /\bplease (log ?in|sign ?in)\b/i,
+  /\bnot logged in\b/i,
+  /\b(login|session|token) (expired|invalid)\b/i,
+  /\bsubscription (required|expired)\b/i,
+  // ── 모델이 쓴 기계 자기보고 (2026-08-08 ollama 실측) ──
+  // "The system encountered a timeout error while processing a request. No further
+  // function calls are required. Please retry the operation..." — 도구 왕복이 무너진 뒤
+  // 로컬 모델이 뱉은 문장이 최종 답으로 저장됐다. 사람에게 하는 답이 아니라 프로토콜 잡담.
+  /\bno further (function|tool) calls?\b/i,
+  /\bsystem encountered (a|an) [a-z]+ error\b/i,
+  /\bretry the (operation|request)\b/i,
+];
+
+/** 종류 추정 — 표식이 없으니 문구에서. 조율은 여기 한 곳. */
+function kindOf(text) {
+  if (/\btimed? ?out\b|\btimeout\b/i.test(text)) return "timeout";
+  if (/\b(log ?in|sign ?in|logged in|expired|unauthorized|subscription)\b/i.test(text)) return "auth";
+  if (/\b(limit|quota|credits?|resets?|try again)\b/i.test(text)) return "quota";
+  return "refused";
+}
+
+/**
+ * 텍스트가 산출물이 아니라 거절 고지문인가.
+ * @returns {{ kind: "quota"|"auth"|"refused"|"timeout", message: string } | null}
+ */
+function detectRuntimeRefusal(text) {
+  const t = String(text || "").trim();
+  if (!t || t.length > MAX_NOTICE_LENGTH) return null;
+  // 구조가 보이면 산출물이다 — JSON, 코드펜스, 다문단.
+  if (t.includes("{") || t.includes("```") || /\n\s*\n/.test(t)) return null;
+  if (!NOTICE_PATTERNS.some((re) => re.test(t))) return null;
+  return { kind: kindOf(t), message: t };
+}
+
+module.exports = { detectRuntimeRefusal, MAX_NOTICE_LENGTH };

package/engine/runtimes/auth-evidence.cjs

@@ -0,0 +1,78 @@
+"use strict";
+/*
+ * runtimes/auth-evidence — CLI 런타임의 "로그인 흔적" 관측.
+ *
+ * 배경(2026-08-05 감사, 결함 B): doctor의 런타임 검사는 which(bin) 하나였다.
+ * codex가 로그아웃 상태여도 "✓ runtimes … ✓ active runtime — codex" +
+ * "doctor: all clear"가 나갔고, 사용자는 첫 실행이 죽을 때까지 몰랐다.
+ * 설치 여부와 인증 여부는 다른 축이다.
+ *
+ * 계약 — 증거이지 증명이 아니다:
+ *  - 여기서는 각 CLI가 로그인 시 남기는 로컬 산출물(파일·키체인 항목·환경 변수)의
+ *    존재만 관측한다. 모델 호출·네트워크 왕복 없음. 파일 내용도 읽지 않는다
+ *    (토큰 만료까지는 판정하지 않는다 — 그건 실행이 판정한다).
+ *  - 산출물이 있어도 만료됐을 수 있으므로 "로그인됨"이라고 단정하지 않는다.
+ *    산출물이 없으면 "흔적 없음 — 로그인이 필요할 수 있음"까지만 말한다.
+ *  - 검사법을 모르는 런타임은 unknown — 모르는 것을 없다고 말하지 않는다.
+ *
+ * 반환: { status: "evidence" | "none" | "unknown", detail: string }
+ */
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const home = () => os.homedir();
+
+function fileEvidence(rel, label) {
+  const p = path.join(home(), ...rel);
+  try {
+    if (fs.existsSync(p) && fs.statSync(p).size > 0) return { status: "evidence", detail: label || p };
+  } catch { /* unreadable == no evidence */ }
+  return null;
+}
+
+function envEvidence(names) {
+  for (const name of names) {
+    if (typeof process.env[name] === "string" && process.env[name].trim()) {
+      return { status: "evidence", detail: `env ${name}` };
+    }
+  }
+  return null;
+}
+
+/** macOS 키체인 generic password 존재 확인 — 값은 읽지 않는다(-w 금지). */
+function keychainEvidence(service, label) {
+  if (process.platform !== "darwin") return null;
+  try {
+    const res = spawnSync("security", ["find-generic-password", "-s", service], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 3000,
+    });
+    if (res.status === 0) return { status: "evidence", detail: label || `keychain ${service}` };
+  } catch { /* security unavailable == no evidence */ }
+  return null;
+}
+
+const CHECKS = {
+  "claude-code": () =>
+    envEvidence(["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"])
+    || keychainEvidence("Claude Code-credentials", "keychain")
+    || fileEvidence([".claude", ".credentials.json"], "~/.claude/.credentials.json"),
+  codex: () =>
+    fileEvidence([".codex", "auth.json"], "~/.codex/auth.json")
+    || envEvidence(["OPENAI_API_KEY"]),
+  gemini: () =>
+    fileEvidence([".gemini", "oauth_creds.json"], "~/.gemini/oauth_creds.json")
+    || envEvidence(["GEMINI_API_KEY", "GOOGLE_API_KEY"]),
+};
+
+function runtimeAuthEvidence(kind) {
+  const check = CHECKS[kind];
+  if (!check) return { status: "unknown", detail: "no local evidence check for this runtime" };
+  const found = check();
+  if (found) return found;
+  return { status: "none", detail: "" };
+}
+
+module.exports = { runtimeAuthEvidence };

package/engine/runtimes/detect.cjs

@@ -12,6 +12,9 @@ const RUNTIME_BIN = {
   "claude-code": "claude",
   codex: "codex",
   gemini: "gemini",
+  // Antigravity CLI — gemini 후속. 공식 gemini CLI가 계정 티어로 죽어도(IneligibleTierError,
+  // 실측 2026-08-06) 이쪽은 산다. 데스크탑 gemini 러너의 agy 경로와 같은 실물.
+  agy: "agy",
   kimi: "kimi",
   grok: "grok",
   cursor: "cursor-agent",

package/engine/runtimes/resolve.cjs

@@ -10,7 +10,7 @@ const { RUNTIME_BIN, whichSync, listAvailableCliRuntimes, activeRuntimeRow } = r
 // Session이 실제 드라이버를 갖춘 런타임만 실행 대상으로 삼는다.
 // CLI는 native-host, Ollama는 로컬 API loop를 쓴다. 다른 드라이버가 포팅되면
 // 해당 집합에 추가한다(조용한 오폭 방지).
-const CLI_EXECUTABLE_KINDS = new Set(["claude-code", "codex", "gemini"]);
+const CLI_EXECUTABLE_KINDS = new Set(["claude-code", "codex", "gemini", "agy"]);
 const API_EXECUTABLE_KINDS = new Set(["ollama"]);
 const EXECUTABLE_KINDS = new Set([
   ...CLI_EXECUTABLE_KINDS,

package/engine/sessions/prompt.cjs

@@ -190,6 +190,22 @@ function augmentSystem(db, baseSystem, ctx, withEmitter, request = "") {
   if (connectionSkill) sys += "\n\n" + connectionSkill;
   const mem = cliMemoryContext(db, ctx && ctx.projectPath, ctx && ctx.agentId, request);
   if (mem) sys += "\n\n" + mem;
+  // 도구 접근 고지 — 터미널에는 이게 아예 없었다. 도구가 붙지 않은 턴에서 CLI는 아무
+  // 말도 하지 않았고, 에이전트는 "이 기계엔 도구가 없다"고 단정하거나 없는 도구를
+  // 불렀다. Desktop `shared/tool-access-notice.ts`와 같은 문장을 낸다(패리티 테스트로 고정).
+  //
+  // ★메모리 블록보다 **앞**에 둔다. 메모리 코어 예산은 `## Memory` 이후를 잘라서 재므로
+  // (test/memory-prompt-budget.cjs), 뒤에 붙이면 도구 고지가 메모리 예산으로 잘못 계산된다.
+  // 고지는 메모리 블록의 일부가 아니다.
+  try {
+    const { buildToolAccessNotice } = require("../tools/access-notice.cjs");
+    sys += "\n\n" + buildToolAccessNotice({
+      availableTools: (ctx && Array.isArray(ctx.availableTools)) ? ctx.availableTools : [],
+      // 터미널은 Hub 카탈로그를 hephaestus-network MCP로만 본다. 그 서버가 이번 턴에
+      // 붙지 않았으면 "찾아보라"고 말하면 안 된다 — 부를 수 없는 도구를 안내하는 셈이다.
+      hubCatalogAvailable: Boolean(ctx && ctx.hubCatalogAvailable),
+    });
+  } catch { /* 고지 실패가 턴을 막지 않는다 */ }
   if (withEmitter) {
     sys += "\n\n" + memoryEmitterPromptFor(request, arch, ctx && ctx.turnId, ctx && ctx.permission);
     const credentialReminder = credentialIndexReminderFor(request);

package/engine/sessions/session.cjs

@@ -205,12 +205,21 @@ class Session extends EventEmitter {
     try {
       const { augmentSystem } = require("./prompt.cjs");
       const projectPath = governedTurn ? governedTurn.projectPath : memoryTurn.initializedProjectPath(this.cwd);
+      // 이번 턴에 실제로 붙는 도구를 고지에 넘긴다. 권한이 낮아 목록을 읽지 않는 턴은
+      // 빈 배열이 되고, 고지는 "붙은 도구가 없다"고 정확히 말한다 — 침묵하지 않는다.
+      const consentedServers = this._consentedMcpServers();
+      const toolNames = consentedServers
+        .map((server) => String((server && (server.name || server.id)) || "").trim())
+        .filter(Boolean);
       systemPrompt = augmentSystem(this.db, systemPrompt, {
         lang: this.lang,
         projectPath,
         agentId: this.agent.id,
         turnId: governedTurn && governedTurn.memoryTurn.turnId,
         permission: this.permission,
+        availableTools: toolNames,
+        // Hub 카탈로그는 hephaestus-network MCP를 통해서만 보인다.
+        hubCatalogAvailable: toolNames.some((name) => /hephaestus[-_]?network|agentlas/i.test(name)),
       }, true, prompt);
     } catch { /* 프롬프트 증강 실패는 턴을 막지 않는다 — 원 프롬프트로 진행 */ }
 
@@ -273,7 +282,13 @@ class Session extends EventEmitter {
       if (this._timeoutConfig) req.timeoutConfig = this._timeoutConfig;
       try {
         res = await nativeHost.runNativeTurn(req);
-        if (res && res.error && !res.text && !res.finalText) {
+        /*
+         * ★복구 게이트는 **표식**으로 연다 — `!res.text`를 조건에 끼우면 안 된다.
+         * 실측(2026-08-06): claude 한도 거절은 error와 함께 거절문이 text에도 실려 온다.
+         * 그래서 `!res.text`가 영원히 거짓이 되어, 예비 런타임이 등록돼 있는데도
+         * 복구가 한 번도 발화하지 않았다. 실패는 error가 말하고, text는 표시용이다.
+         */
+        if (res && res.error) {
           const nextRuntime = this._nextRecoveryRuntime();
           if (nextRuntime) {
             const privateEvidence = [...this._privateRecoveryEvidence, String(res.error)]
@@ -411,7 +426,14 @@ class Session extends EventEmitter {
     }
     if (res && res.error) {
       this.status = "failed";
-      this.lastError = null;
+      /*
+       * ★사유를 버리지 않는다. 예전에는 여기서 null로 지워서, daemon이 run_history에
+       * "runtime turn failed"라는 고정 문자열만 남기고 run/build는 아무 말 없이 exit 1이었다
+       * — 사람이 알아야 고칠 수 있는 것(한도 리셋 시각, 로그인 필요)을 아는 쪽이 지웠다.
+       * 렌더러 완곡 문구는 Ui 계층이 따로 지킨다(recovery-presentation-contract) —
+       * 기록과 화면은 다른 문제다.
+       */
+      this.lastError = String(res.error).slice(0, 2000);
       this._record({ type: "turn-end", at: Date.now(), ok: false, recoveryRequired: true });
     } else {
       this.status = "done";

package/engine/telegram/connect.cjs

@@ -0,0 +1,202 @@
+"use strict";
+/*
+ * telegram/connect — 터미널 독립 Telegram 연결 (2026-08-06).
+ *
+ * 배경(오너): 데스크탑에서 쉽게 되는데 터미널이 왜 안 되냐. 확인해 보니
+ * 데스크탑 electron/telegram/connect.ts(2193줄)의 대부분은 Electron이 BotFather
+ * **브라우저 창을 자동 조종**해 봇을 자동 생성하는 편의 로직이다. 실제 연결
+ * 코어는 순수 HTTPS(api.telegram.org)이고 Electron이 필요 없다:
+ *   verifyBotToken(getMe) → 바인딩 저장 → getUpdates 폴링으로 방 귀속 → sendMessage.
+ * 그 코어만 이식한다. 봇 토큰은 사용자가 @BotFather로 만들어 stdin으로 준다
+ * (비밀은 argv 금지 — 히스토리·ps 노출). 저장은 0600 파일(standalone Node에서
+ * keytar는 macOS 키체인에 막혀 멈추므로 — creds.cjs 계약과 동일).
+ *
+ * 데스크탑과 같은 telegram_bindings 테이블·같은 페어링 규칙을 쓴다(공유 스키마).
+ */
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { userDataDir } = require("../core/paths.cjs");
+const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
+
+const TELEGRAM_REQUEST_TIMEOUT_MS = 20_000;
+
+/** 순수 HTTPS. fetch 주입 가능(테스트). */
+async function telegramApi(token, method, payload, { fetchImpl } = {}) {
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== "function") throw new Error("this runtime has no fetch");
+  const longPoll = method === "getUpdates" && typeof payload.timeout === "number" ? Math.max(0, payload.timeout) : 0;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(`Telegram ${method} timed out`)), TELEGRAM_REQUEST_TIMEOUT_MS + longPoll * 1000);
+  try {
+    const res = await doFetch(`https://api.telegram.org/bot${token}/${method}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok || !json || json.ok !== true) {
+      throw new Error((json && json.description) || `Telegram ${method} failed (${res.status})`);
+    }
+    return json.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function verifyBotToken(token, opts) {
+  const me = await telegramApi(token, "getMe", {}, opts);
+  if (!me || !me.is_bot) throw new Error("that token does not belong to a Telegram bot");
+  return me;
+}
+
+// ── 토큰 비밀 저장 (0600 파일) ─────────────────────────────────────────────
+function tokenDir() {
+  const dir = path.join(userDataDir(), "telegram");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+function tokenFile(id) { return path.join(tokenDir(), `${id}.token`); }
+function saveToken(id, token) { fs.writeFileSync(tokenFile(id), token, { encoding: "utf8", mode: 0o600 }); }
+function readToken(id) {
+  try { return fs.readFileSync(tokenFile(id), "utf8").trim() || null; } catch { return null; }
+}
+function deleteToken(id) { try { fs.rmSync(tokenFile(id)); } catch { /* gone */ } }
+function tokenFingerprint(token) { return crypto.createHash("sha256").update(token).digest("hex").slice(0, 24); }
+
+// ── 바인딩 ─────────────────────────────────────────────────────────────────
+function listBindings(db) {
+  try { return db.prepare("SELECT * FROM telegram_bindings ORDER BY rowid DESC").all(); } catch { return []; }
+}
+function getBinding(db, id) {
+  try { return db.prepare("SELECT * FROM telegram_bindings WHERE id=?").get(id) || null; } catch { return null; }
+}
+
+/** 봇 토큰으로 바인딩을 만든다(방 미페어링). 반환: {id, botUsername}. */
+async function startConnection(db, targetKind, targetId, token, opts) {
+  const me = await verifyBotToken(token, opts);
+  const id = crypto.randomUUID();
+  const now = new Date().toISOString();
+  runWriteTransaction(db, () => {
+    db.prepare(
+      "INSERT INTO telegram_bindings (id, target_kind, target_id, bot_user_id, bot_username, bot_display_name, status, enabled, token_saved, token_fingerprint, created_at, updated_at) " +
+      "VALUES (?,?,?,?,?,?,'waiting_for_chat',1,1,?,?,?)",
+    ).run(id, targetKind, targetId, me.id, me.username || null, me.first_name || null, tokenFingerprint(token), now, now);
+  });
+  saveToken(id, token);
+  // 남은 웹훅이 있으면 getUpdates가 막히므로 제거(있어도 무해).
+  await telegramApi(token, "deleteWebhook", { drop_pending_updates: false }, opts).catch(() => null);
+  return { id, botUsername: me.username || null };
+}
+
+/**
+ * getUpdates 폴링으로 첫 private 메시지의 chat을 이 바인딩에 귀속한다.
+ * 보안: 데스크탑과 같은 규칙 — 미페어링·enabled·waiting_for_chat 인 신선 바인딩
+ * (30분 이내)에만, private 채팅만. 반환: 페어링된 바인딩 또는 null(시간초과).
+ */
+async function pairByPolling(db, id, { timeoutMs = 120_000, opts, onWait } = {}) {
+  const token = readToken(id);
+  if (!token) throw new Error("no stored token for this binding");
+  const deadline = Date.now() + timeoutMs;
+  let offset = (getBinding(db, id) || {}).last_update_id || 0;
+  while (Date.now() < deadline) {
+    if (typeof onWait === "function") onWait();
+    let updates;
+    try {
+      updates = await telegramApi(token, "getUpdates", { offset: offset + 1, timeout: 25, allowed_updates: ["message"] }, opts);
+    } catch { updates = []; }
+    for (const update of updates || []) {
+      if (typeof update.update_id === "number") offset = Math.max(offset, update.update_id);
+      const message = update.message;
+      if (!message || !message.chat || message.chat.type !== "private") continue;
+      // 신선 미페어링 바인딩인지 재확인(경합 방지) 후 귀속.
+      const row = getBinding(db, id);
+      if (!row || row.telegram_chat_id || row.status !== "waiting_for_chat") continue;
+      const createdAt = Date.parse(row.created_at);
+      if (!Number.isFinite(createdAt) || Date.now() - createdAt > 30 * 60 * 1000) throw new Error("pairing window expired (30 min) — reconnect");
+      const now = new Date().toISOString();
+      const title = message.chat.title || [message.chat.first_name, message.chat.last_name].filter(Boolean).join(" ") || message.chat.username || String(message.chat.id);
+      runWriteTransaction(db, () => {
+        db.prepare("UPDATE telegram_bindings SET telegram_chat_id=?, telegram_chat_title=?, status='chat_paired', last_update_id=?, updated_at=? WHERE id=?")
+          .run(String(message.chat.id), title, offset, now, id);
+      });
+      return getBinding(db, id);
+    }
+    if (offset) {
+      runWriteTransaction(db, () => {
+        db.prepare("UPDATE telegram_bindings SET last_update_id=MAX(last_update_id,?), updated_at=? WHERE id=?").run(offset, new Date().toISOString(), id);
+      });
+    }
+  }
+  return null;
+}
+
+/** 페어링된 방에 확인 메시지를 보낸다. */
+async function sendTest(db, id, text, opts) {
+  const row = getBinding(db, id);
+  if (!row) throw new Error("binding not found");
+  if (!row.telegram_chat_id) throw new Error("this binding is not paired to a chat yet");
+  const token = readToken(id);
+  if (!token) throw new Error("no stored token for this binding");
+  await telegramApi(token, "sendMessage", { chat_id: row.telegram_chat_id, text }, opts);
+  return true;
+}
+
+function removeBinding(db, id) {
+  runWriteTransaction(db, () => {
+    db.prepare("DELETE FROM telegram_bindings WHERE id=?").run(id);
+  });
+  deleteToken(id);
+}
+
+/*
+ * 브라우저 조종으로 BotFather 토큰을 자동 포착 (2026-08-06).
+ * 데스크탑 electron/telegram/connect.ts 의 readTelegramWebState 와 같은 방식:
+ * 페이지 innerText 에서 봇 토큰 정규식을 읽는다. 데스크탑은 Electron
+ * executeJavaScript, 여기서는 CDP Runtime.evaluate — 동형. 봇 생성(/newbot)은
+ * 열린 Agentlas Chrome 에서 사용자가 하거나 이미 만든 봇을 열면 되고, 토큰은
+ * 터미널이 페이지에서 직접 읽어 복붙을 없앤다.
+ *
+ * 반환: 포착한 토큰 문자열 또는 null(시간초과). 브라우저(CDP)가 없으면
+ * cdp_unavailable 로 던진다 — 호출자가 수동 토큰 경로로 안내.
+ */
+const BOTFATHER_WEB_URL = "https://web.telegram.org/k/#@BotFather";
+const TOKEN_RE_SRC = "\\b\\d{8,12}:[A-Za-z0-9_-]{30,}\\b";
+
+async function captureBotTokenViaBrowser({ timeoutMs = 180_000, onWait } = {}) {
+  const cdp = require("../browser/cdp.cjs");
+  if (!(await cdp.cdpReady())) {
+    const err = new Error("Agentlas browser (CDP) is not running");
+    err.code = "cdp_unavailable";
+    throw err;
+  }
+  const page = await cdp.attachPage();
+  try {
+    await page.navigate(BOTFATHER_WEB_URL, { waitMs: 2500 });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (typeof onWait === "function") onWait();
+      // 페이지 텍스트에서 마지막 토큰을 읽는다(가장 최근 발급).
+      let token = null;
+      try {
+        token = await page.evalExpr(
+          "(document.body && document.body.innerText ? document.body.innerText : '').match(/" + TOKEN_RE_SRC + "/g)?.slice(-1)[0] || null",
+        );
+      } catch { token = null; }
+      if (token) return token;
+      await new Promise((r) => setTimeout(r, 1200));
+    }
+    return null;
+  } finally {
+    page.close();
+  }
+}
+
+module.exports = {
+  telegramApi, verifyBotToken,
+  startConnection, pairByPolling, sendTest, removeBinding,
+  listBindings, getBinding,
+  saveToken, readToken, deleteToken, tokenFingerprint,
+  captureBotTokenViaBrowser, BOTFATHER_WEB_URL,
+};

package/engine/tools/access-notice.cjs

@@ -0,0 +1,86 @@
+// 도구 접근 고지 — Desktop `shared/tool-access-notice.ts`의 터미널 미러.
+//
+// 정본은 Desktop 쪽이고, 이 파일은 **같은 문장을 내야 한다**. 두 벌이 갈라지면 같은
+// 제품이 표면마다 다른 말을 하게 되고, 사용자는 어느 쪽이 맞는지 알 수 없다.
+// `test/tool-access-notice-parity.cjs`가 두 구현을 같은 입력으로 돌려 대조한다.
+//
+// 터미널에는 이 고지가 **아예 없었다**. 도구가 붙지 않은 실행에서 CLI는 아무 말도 하지
+// 않았고, 에이전트는 "이 기계엔 도구가 없다"고 단정하거나 없는 도구를 부르거나 그냥
+// 침묵했다. 도구가 없을 때가 안내가 가장 필요한 순간이다.
+
+"use strict";
+
+const DEFAULT_RESOLVE_TOOL = "agentlas_resolve_plugins";
+
+/**
+ * 모든 표면이 공유하는 도구 접근 고지.
+ * 절대 빈 문자열을 반환하지 않는다 — 붙은 도구가 없다는 사실 자체가 정보다.
+ *
+ * @param {{
+ *   availableTools: string[],
+ *   blockedTools?: string[],
+ *   pendingApprovalTools?: string[],
+ *   hubCatalogAvailable: boolean,
+ *   hubCatalogError?: string|null,
+ *   resolveToolName?: string,
+ * }} input
+ * @returns {string}
+ */
+function buildToolAccessNotice(input) {
+  const resolveTool = (input.resolveToolName || "").trim() || DEFAULT_RESOLVE_TOOL;
+  const clean = (list) => (Array.isArray(list) ? list : []).filter((name) => String(name || "").trim().length > 0);
+  const available = clean(input.availableTools);
+  const blocked = clean(input.blockedTools);
+  const pending = clean(input.pendingApprovalTools);
+  const lines = [];
+
+  lines.push(
+    available.length > 0
+      ? `Tools available in this run: ${available.join(", ")}.`
+      : "No tools are connected in this run.",
+  );
+
+  if (pending.length > 0) {
+    lines.push(
+      `Already attached but switched off, waiting for the user to approve local execution: ${pending.join(", ")}. ` +
+      "Ask the user to approve it instead of installing anything new.",
+    );
+  }
+
+  if (input.hubCatalogAvailable) {
+    lines.push(
+      `Before telling the user a capability is unavailable, call ${resolveTool} with the capability you need. ` +
+      "The Agentlas Hub catalog covers integrations that are not installed here yet.",
+    );
+  } else if (input.hubCatalogError) {
+    lines.push(
+      `The Agentlas Hub catalog could not be reached this run (${input.hubCatalogError}). ` +
+      "Say that the catalog is unreachable rather than that no such tool exists.",
+    );
+  } else {
+    lines.push(
+      "The Agentlas Hub catalog is not reachable from this surface. " +
+      "Say what you cannot do and why; do not claim a capability that is not connected.",
+    );
+  }
+
+  lines.push(
+    "Never install or enable a tool on your own. Show the slug, what it will be allowed to do, " +
+    "and whether it needs credentials, then let the user decide.",
+  );
+
+  if (blocked.length > 0) {
+    lines.push(
+      `Matched but unusable until credentials are set: ${blocked.join(", ")}. ` +
+      "Ask for those only if this task actually needs them.",
+    );
+  }
+
+  lines.push(
+    "If nothing covers the need, say so plainly. Do not describe a tool call you did not make.",
+  );
+
+  return lines.join("\n");
+}
+
+module.exports = { buildToolAccessNotice, DEFAULT_RESOLVE_TOOL };