agentlas 0.5.2 → 0.6.0

package/README.md

@@ -14,6 +14,17 @@ agents and teams, build new ones, and run the full Agentlas OS surface
 (`build` · `search` · `install` · `storm` · `network` · …) from one command.
 Claude Code style, standalone: **no desktop app required.**
 
+Agentlas Terminal is the already-shipped independent terminal product. It is
+not a Desktop `cli/` mirror and does not require the Desktop app to run.
+
+> **We are Agent Trust. Your agent is not a program. It is an asset. — Agentlas —**
+
+Agent Trust means owner-scoped, portable, inspectable, and restorable agent
+packages. It is a product principle, not a claim of regulated financial or
+legal trust services. Private Agent Cloud stores owned packages; this existing
+Terminal verifies and runs their local execution copies through supported
+runtimes.
+
 ```sh
 npm install -g agentlas
 agentlas
@@ -66,14 +77,30 @@ agentlas chats [n]                 # 최근 대화 목록
 **에이전트 & 허브** (Agentlas OS 표면)
 ```sh
 agentlas search "할 일"            # Hub에서 에이전트 발견            (hep-search)
-agentlas install <slug>            # Hub 에이전트 설치                (hep-cloud)
+agentlas install <slug>            # 공개 Hub 에이전트 설치           (hep-cloud)
 agentlas build "요청"              # 에이전트/팀 빌드·수리·패키징     (hep-build)
-agentlas upload <경로>             # 에이전트 패키징+Hub 배포         (hep-upload)
+agentlas upload <경로>             # 내 Agent Cloud에 비공개 저장    (hep-upload)
+agentlas upload <경로> --visibility marketplace
+                                  # 호환 flag: Agentlas Hub 공개 발행
 agentlas connect                   # Telegram/플랫폼 연결             (hep-connect)
 agentlas import <폴더>             # 로컬 에이전트/팀 임포트
 agentlas list                      # 설치된 에이전트/회사 + 활성 런타임
 ```
 
+**내 Agent Cloud 자산**
+```sh
+agentlas cloud save <경로>         # 소유자 전용 비공개 저장(공개 심사/라우팅 카드 없음)
+agentlas cloud publish <경로>      # Agentlas Hub에 명시적으로 공개 발행
+agentlas cloud list                # 로그인한 소유자의 비공개 패키지 조회
+agentlas cloud restore <slug>      # 전체 hash 검증 후 이 컴퓨터에 exact snapshot 복원
+```
+
+비공개 저장도 업로드 전 로컬에서 비밀값, 안전하지 않은 경로, 파일별 hash와
+전체 package hash를 검사한다. 공개 Hub 발행에만 라우팅 카드와 공개 검토가 붙는다.
+
+`agentlas cloud install <slug>`은 기존 호환 명령이며 공개 Hub 설치다. 비공개
+Agent Cloud 소유자 복원은 반드시 `agentlas cloud restore <slug>`를 사용한다.
+
 **실행 엔진**
 ```sh
 agentlas storm "목표"              # 견고 파이프라인 라우팅→검증→실행 (Stormbreaker) [--research]
@@ -107,12 +134,26 @@ agentlas setup                     # 온보딩 다시 실행
 ```sh
 agentlas hep <sub…>                # 전체 Hephaestus 패스스루 (wizard·security·cards·ao·plugins…)
 agentlas netadmin <sub>            # 로컬 네트워크 관리 (init|status|reindex|bench)
-agentlas cloud <sub>               # 에이전트 패키징 (wizard|security|bundle|package|publish)
+agentlas cloud <sub>               # 자산 저장·공개·복원 (save|publish|package|list|restore|…)
 ```
 
 공통 옵션: `--runtime claude-code|codex|gemini` · `--permission read|write|full`
 REPL 안에서는 `/`로 명령 팔레트 (`/build` `/search` `/storm` `/network` …).
 
+권한은 이름과 실제 런타임 실행 범위를 일치시킨다.
+
+| Agentlas 권한 | Claude Code | Codex | Gemini CLI |
+| --- | --- | --- | --- |
+| `read` | `plan` | `read-only` sandbox | `plan` |
+| `write` | `acceptEdits` | `workspace-write` sandbox | `auto_edit` |
+| `full` | permission 검사 우회 | approval + sandbox 우회 | `yolo` |
+
+`write`는 무제한 권한의 다른 이름이 아니다. 외부 상태를 바꿀 수 있는 MCP/Playwright
+도구는 `full` 턴에서만 주입한다. 입력창에서 `Shift-Tab`으로 권한을 순환할 수 있지만,
+`write → full`은 5초 안에 두 번 연속 눌러야 하며 이 변경은 현재 세션에만 적용된다.
+실행 중 `Ctrl-T`는 Claude Todo/Task, Codex `todo_list`, Gemini `write_todos`가 실제로
+보낸 체크리스트만 열고 접는다. 일반 Bash/Read 실행을 계획 항목처럼 꾸며내지 않는다.
+
 ## 동작 방식
 
 런처(`bin/agentlas.cjs`)가 이 패키지의 `engine/`(정본)을 시스템 Node로 실행한다 —
@@ -149,6 +190,7 @@ rm ~/.local/bin/agentlas             # install.sh 설치 시
 
 ## License
 
-Apache-2.0 — engine sources are vendored from the public
-[agentlas-ai/agentlas-desktop](https://github.com/agentlas-ai/agentlas-desktop) repo
-(see `engine/ENGINE_META.json` for the exact version/commit).
+Apache-2.0 — Agentlas Terminal is the independent terminal runtime for the
+[Agentlas OS](https://github.com/agentlas-ai/Agentlas-OS) package contract. Its
+`engine/` directory is maintained and released from this repository; it is not
+a generated mirror of Agentlas Desktop.

package/bin/agentlas.cjs

@@ -51,14 +51,41 @@ function dbPath() {
 // require.resolve가 아니라 실제 로드로 판별한다 — ABI가 깨진 better-sqlite3나
 // node:sqlite가 아직 없는/플래그가 필요한 Node(≤22.4 등)를 정확히 걸러낸다.
 function probeSqliteDriver() {
-  try { require("better-sqlite3"); return "better-sqlite3"; } catch { /* absent or ABI-broken */ }
   try {
-    const { DatabaseSync } = require("node:sqlite");
-    if (DatabaseSync) return "node:sqlite";
+    const Database = require("better-sqlite3");
+    // Loading the JS wrapper alone does not prove that its native binding matches
+    // this Node ABI. Exercise the constructor before reporting it to --where.
+    const db = new Database(":memory:");
+    db.close();
+    return "better-sqlite3";
+  } catch { /* absent or ABI-broken */ }
+  try {
+    const { DatabaseSync } = loadNodeSqliteQuietly();
+    if (DatabaseSync) {
+      const db = new DatabaseSync(":memory:");
+      db.close();
+      return "node:sqlite";
+    }
   } catch { /* not available without a flag on this Node */ }
   return null;
 }
 
+function loadNodeSqliteQuietly() {
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = function agentlasSqliteWarningFilter(warning, ...args) {
+    const message = typeof warning === "string" ? warning : String((warning && warning.message) || warning || "");
+    const type = typeof args[0] === "string" ? args[0] : "";
+    if (type === "ExperimentalWarning" && /SQLite/i.test(message)) return;
+    if (/SQLite is an experimental feature/i.test(message)) return;
+    return originalEmitWarning.call(process, warning, ...args);
+  };
+  try {
+    return require("node:sqlite");
+  } finally {
+    process.emitWarning = originalEmitWarning;
+  }
+}
+
 function openSqlite(p) {
   try {
     const Database = require("better-sqlite3");
@@ -69,7 +96,7 @@ function openSqlite(p) {
   if (major < 22) {
     throw new Error(`Node ${process.version} — better-sqlite3가 없으면 Node 22+ (node:sqlite)가 필요합니다.`);
   }
-  const { DatabaseSync } = require("node:sqlite");
+  const { DatabaseSync } = loadNodeSqliteQuietly();
   const db = new DatabaseSync(p);
   return { exec: (sql) => db.exec(sql), close: () => db.close(), driver: "node:sqlite" };
 }
@@ -86,16 +113,34 @@ function bootstrapDbIfMissing() {
   }
   fs.mkdirSync(path.dirname(p), { recursive: true });
   const sql = fs.readFileSync(schemaFile, "utf8");
-  const db = openSqlite(p);
+  // DB를 정식 경로에서 직접 만들면 두 첫 실행이 모두 exists=false를 본 뒤 한 프로세스의
+  // 실패 cleanup이 다른 프로세스의 정상 DB까지 지울 수 있다. 각자 같은 볼륨의 임시 DB를
+  // 완성하고 hard-link(EEXIST=다른 프로세스 승리)로만 정식 이름을 원자 획득한다.
+  const temp = `${p}.bootstrap-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`;
+  const db = openSqlite(temp);
   try {
     db.exec(sql);
   } catch (e) {
     db.close();
-    try { fs.rmSync(p); } catch { /* leave partial for inspection */ }
+    try { fs.rmSync(temp, { force: true }); } catch { /* leave temp for inspection */ }
     throw new Error(`DB 부트스트랩 실패: ${e.message}`);
   }
   db.close();
-  return { created: true, path: p };
+  let created = false;
+  try {
+    fs.linkSync(temp, p);
+    created = true;
+  } catch (e) {
+    if (!e || e.code !== "EEXIST") {
+      throw new Error(`DB 원자 부트스트랩 전환 실패: ${e && e.message ? e.message : e}`);
+    }
+  } finally {
+    try { fs.rmSync(temp, { force: true }); } catch { /* noop */ }
+    try { fs.rmSync(temp + "-journal", { force: true }); } catch { /* noop */ }
+    try { fs.rmSync(temp + "-wal", { force: true }); } catch { /* noop */ }
+    try { fs.rmSync(temp + "-shm", { force: true }); } catch { /* noop */ }
+  }
+  return { created, path: p };
 }
 
 function main() {
@@ -173,4 +218,6 @@ function main() {
   });
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { bootstrapDbIfMissing, dbPath, userDataDir, probeSqliteDriver };

package/engine/agentlas-api-agent.cjs

@@ -300,7 +300,7 @@ async function runOpenAILoop(req) {
 // ── Ollama (openai 스타일 tools, /api/chat) ──────────────
 async function runOllamaLoop(req) {
   const { ctx, ui } = req;
-  const host = process.env.OLLAMA_HOST || "http://127.0.0.1:11434";
+  const host = (req.ctx.env && req.ctx.env.OLLAMA_HOST) || process.env.OLLAMA_HOST || "http://127.0.0.1:11434";
   const messages = req.messages.slice();
   if (!messages.length || messages[0].role !== "system") messages.unshift({ role: "system", content: req.system });
   const toolDefs = tools.openaiTools(ctx.permission);

package/engine/agentlas-banner.cjs

@@ -4,6 +4,8 @@
  */
 const path = require("node:path");
 const os = require("node:os");
+const permissions = require("./agentlas-permissions.cjs");
+const { truncateWidth, visWidth } = require("./agentlas-composer.cjs");
 
 // AGENTLAS wordmark (block letters). Rendered with a brand gradient across columns.
 const WORDMARK = [
@@ -45,28 +47,9 @@ function shorten(p) {
 // AGENTLAS wordmark, per-column brand gradient. Falls back to plain / compact.
 function renderMascot(ui) {
   const c = ui.c;
-  const cols = (ui.out && ui.out.columns) || 80;
-  if (!ui.enabled) {
-    ui.line("  AGENTLAS");
-    return;
-  }
-  // Narrow terminal → compact wordmark.
-  if (cols < 72) {
-    ui.line("  " + c.bold(c.emerald(WORDMARK_COMPACT)));
-    return;
-  }
-  const g = (rgb, s) => `\x1b[1;38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${s}\x1b[0m`;
-  for (const rowStr of WORDMARK) {
-    let outLine = "";
-    const n = rowStr.length || 1;
-    for (let i = 0; i < rowStr.length; i++) {
-      const ch = rowStr[i];
-      if (ch === " ") { outLine += " "; continue; }
-      const idx = Math.min(GRADIENT.length - 1, Math.floor((i / n) * GRADIENT.length));
-      outLine += g(GRADIENT[idx], ch);
-    }
-    ui.line(outLine);
-  }
+  // A one-line mark keeps first launch and setup compact. The old six-row wordmark
+  // remains exported for recordings/assets, but is no longer startup chrome.
+  ui.line("  " + c.bold(c.emerald(WORDMARK_COMPACT)));
 }
 
 function stripAnsi(s) {
@@ -87,48 +70,49 @@ function row(ui, width, text) {
   ui.line(ui.c.faint("│ ") + ui.c.text(fit(text, inner)) + ui.c.faint(" │"));
 }
 
+function sessionValues(ctx) {
+  const ui = ctx.ui;
+  return {
+    version: ctx.version || readVersion(),
+    subject: ctx.subjectLabel || ui.t("composer.autoroute"),
+    permission: permissions.copy(ctx.permission || "write", ui.lang).label,
+    runtime: ctx.runtimeLabel || "—",
+    cwd: ctx.cwd ? shorten(ctx.cwd) : process.cwd(),
+  };
+}
+
 function renderStatusCard(ctx, opts = {}) {
   const ui = ctx.ui;
   const c = ui.c;
-  const cols = ui.out.columns || 80;
-  const width = Math.max(54, Math.min(cols - 2, 78));
-  const version = ctx.version || readVersion();
-  const subject = ctx.subjectLabel || "Pick an agent, choose a company, or type a task";
-  const permission = ctx.permission || "write";
-  const runtime = ctx.runtimeLabel || "(not configured)";
-  const cwd = ctx.cwd ? shorten(ctx.cwd) : process.cwd();
-
+  const value = sessionValues(ctx);
+  const columns = ui.out.columns || 80;
+  const labels = [ui.t("status.runtime"), ui.t("status.agent"), ui.t("status.permission"), ui.t("status.directory")].map((label) => `${label}:`);
+  const labelCells = Math.min(Math.max(...labels.map((label) => visWidth(label))) + 2, Math.max(12, Math.floor(columns * 0.42)));
+  const line = (label, text) => {
+    const labelText = `${label}:`;
+    const padded = labelText + " ".repeat(Math.max(1, labelCells - visWidth(labelText)));
+    const room = Math.max(8, columns - 2 - visWidth(padded));
+    ui.line("  " + c.faint(padded) + c.text(truncateWidth(text, room)));
+  };
   ui.line("");
-  if (!opts.noWordmark) {
-    renderMascot(ui);
-    ui.line("  " + c.dim("the operating system for agents") + (version ? c.faint("   v" + version) : ""));
-  }
-  ui.line("");
-  ui.line(c.faint("╭" + "─".repeat(width - 2) + "╮"));
-  row(ui, width, `model:       ${runtime}`);
-  row(ui, width, `agent:       ${subject}`);
-  row(ui, width, `directory:   ${cwd}`);
-  row(ui, width, `permissions: ${permission}`);
-  ui.line(c.faint("╰" + "─".repeat(width - 2) + "╯"));
-  if (!opts.noTip) {
-    ui.line(
-      "  " +
-        c.bold(c.text("Tip:")) +
-        c.dim(" Type ") +
-        c.faint("/help") +
-        c.dim(" for commands, ") +
-        c.faint("/status") +
-        c.dim(" for session state, ") +
-        c.faint("/exit") +
-        c.dim(" to quit."),
-    );
-  }
+  ui.rule(ui.t("status.title"));
+  line(ui.t("status.runtime"), value.runtime);
+  line(ui.t("status.agent"), value.subject);
+  line(ui.t("status.permission"), value.permission);
+  line(ui.t("status.directory"), value.cwd);
 }
 
 // Main splash. ctx = { ui, version, runtimeLabel, subjectLabel, permission, cwd }
 function renderBanner(ctx) {
-  renderStatusCard(ctx);
-  ctx.ui.line("");
+  const ui = ctx.ui;
+  const c = ui.c;
+  const value = sessionValues(ctx);
+  const room = Math.max(20, (ui.out.columns || 80) - 4);
+  ui.line("");
+  ui.line("  " + c.bold(c.emerald(WORDMARK_COMPACT)) + (value.version ? c.faint("  v" + value.version) : "") + c.dim("  ·  " + ui.t("banner.product")));
+  ui.line("  " + c.text(truncateWidth(ui.t("banner.session", value.runtime, value.subject, value.permission), room)));
+  ui.line("  " + c.faint(truncateWidth(ui.t("banner.location", value.cwd), room)));
+  ui.line("");
 }
 
 // runtime · subject · permission · working folder (no wordmark — used for /status).

package/engine/agentlas-capabilities.cjs

@@ -15,6 +15,7 @@ const RUNTIME_CAPS = {
   "claude-code": { code: true, image: false, label: "claude" },
   codex: { code: true, image: true, label: "codex" }, // Imagen
   gemini: { code: true, image: true, label: "gemini" }, // nano-banana
+  grok: { code: true, image: true, label: "grok" }, // Grok Imagine (generate_image/generate_video, 구독 키리스)
   anthropic: { code: true, image: false, label: "anthropic" },
   openai: { code: true, image: true, label: "openai" }, // gpt-image
   google: { code: true, image: true, label: "google" }, // imagen
@@ -22,6 +23,8 @@ const RUNTIME_CAPS = {
   upstage: { code: true, image: false, label: "solar" }, // Upstage Solar — Korean sovereign LLM (OpenAI-compatible)
 };
 
+// NOTE: grok은 CAPS(멀티모달 능력 인지)만 등록 — 터미널 스폰 러너(RUNTIME_BIN)가 아직 없어
+// CLI_KINDS에 넣으면 repl의 which(RUNTIME_BIN[k]) 탐지가 깨진다. 러너 추가 시 함께 확장할 것.
 const CLI_KINDS = ["claude-code", "codex", "gemini"];
 
 function capsFor(spec) {

package/engine/agentlas-cloud-runtime.cjs

@@ -78,7 +78,7 @@ function buildManifest(root, options = {}) {
     publicExportPolicy: "clean-copy",
     requiredRuntime: ["mcp-client"],
     license: "call-only-default",
-    createdBy: "agentlas-desktop-setup-wizard",
+    createdBy: "agentlas-terminal-setup-wizard",
   };
 }
 
@@ -132,9 +132,46 @@ function loadManifest(root) {
   return JSON.parse(fs.readFileSync(path.join(path.resolve(root), "agentlas.json"), "utf8"));
 }
 
+function globRegex(pattern) {
+  const source = String(pattern || "").replace(/\\/g, "/");
+  let out = "";
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === "*") {
+      if (source[i + 1] === "*") {
+        i += 1;
+        // `**/` includes zero directory levels, so **/secrets/** also
+        // protects a root-level secrets directory.
+        if (source[i + 1] === "/") {
+          i += 1;
+          out += "(?:.*/)?";
+        } else {
+          out += ".*";
+        }
+      } else {
+        out += "[^/]*";
+      }
+      continue;
+    }
+    out += /[.+^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+  }
+  return new RegExp(`^${out}$`, "i");
+}
+
 function matches(filePath, pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
-  return new RegExp(`^${escaped}$`, "i").test(filePath);
+  return globRegex(pattern).test(String(filePath || "").replace(/\\/g, "/"));
+}
+
+function normalizeRequestedPath(requestedPath) {
+  const raw = typeof requestedPath === "string" ? requestedPath.replace(/\\/g, "/") : "";
+  if (!raw || raw.includes("\0") || raw.startsWith("/") || /^[A-Za-z]:\//.test(raw)) return null;
+  const parts = [];
+  for (const segment of raw.split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") return null;
+    parts.push(segment);
+  }
+  return parts.length > 0 ? parts.join("/") : null;
 }
 
 function compileBundle(root) {
@@ -160,17 +197,25 @@ function compileBundle(root) {
 
 function readAgentFile(root, requestedPath) {
   const manifest = loadManifest(root);
-  if ((manifest.denyRead || []).some((pattern) => matches(requestedPath, pattern))) {
-    return { status: "denied", path: requestedPath, reason: "Denied by agentlas.json denyRead.", redacted: true };
+  const safePath = normalizeRequestedPath(requestedPath);
+  if (!safePath) {
+    return { status: "denied", path: String(requestedPath || ""), reason: "Invalid or escaping path.", redacted: true };
+  }
+  if ((manifest.denyRead || []).some((pattern) => matches(safePath, pattern))) {
+    return { status: "denied", path: safePath, reason: "Denied by agentlas.json denyRead.", redacted: true };
   }
-  if (!(manifest.allowRead || []).some((pattern) => matches(requestedPath, pattern))) {
-    return { status: "denied", path: requestedPath, reason: "Path is not in agentlas.json allowRead.", redacted: false };
+  if (!(manifest.allowRead || []).some((pattern) => matches(safePath, pattern))) {
+    return { status: "denied", path: safePath, reason: "Path is not in agentlas.json allowRead.", redacted: false };
+  }
+  const base = path.resolve(root);
+  const abs = path.resolve(base, safePath);
+  if (abs !== base && !abs.startsWith(base + path.sep)) {
+    return { status: "denied", path: safePath, reason: "Path escapes the agent package.", redacted: true };
   }
-  const abs = path.join(path.resolve(root), requestedPath);
-  if (!fs.existsSync(abs)) return { status: "missing", path: requestedPath, reason: "File not found." };
+  if (!fs.existsSync(abs)) return { status: "missing", path: safePath, reason: "File not found." };
   const raw = fs.readFileSync(abs, "utf8");
   const content = redact(raw);
-  return { status: "allowed", path: requestedPath, content, redacted: content !== raw };
+  return { status: "allowed", path: safePath, content, redacted: content !== raw };
 }
 
 function runFieldTest() {
@@ -196,4 +241,13 @@ function runFieldTest() {
   return report;
 }
 
-module.exports = { buildManifest, scanFolder, runWizard, compileBundle, readAgentFile, runFieldTest };
+module.exports = {
+  buildManifest,
+  scanFolder,
+  runWizard,
+  compileBundle,
+  readAgentFile,
+  runFieldTest,
+  matches,
+  normalizeRequestedPath,
+};

package/engine/agentlas-composer.cjs

@@ -2,10 +2,10 @@
 /*
  * agentlas-composer: a raw-mode bottom input box (Claude Code / Hermes style).
  *
- *   ╭────────────────────────────────────────────╮
- *   │ › your message                              │
- *   ╰────────────────────────────────────────────╯
- *     claude-code · full · 12.3k tok · / for commands
+ *   ───────────────────────────────────────────────
+ *   › your message
+ *   ───────────────────────────────────────────────
+ *   ◆ read + write · codex · Agent · / for commands
  *     (slash suggestions render here while typing /…)
  *
  * Single-line field with horizontal scroll (fixed 3-line box → flicker-free clear/redraw).
@@ -13,6 +13,8 @@
  * Zero external deps. Caller falls back to readline when stdin/stdout is not a TTY.
  */
 const readline = require("node:readline");
+const i18n = require("./agentlas-i18n.cjs");
+const permissions = require("./agentlas-permissions.cjs");
 
 // East-Asian width: CJK / Hangul / Kana / fullwidth glyphs occupy 2 terminal cells.
 function isWide(cp) {
@@ -43,6 +45,94 @@ function visWidth(s) {
   return n;
 }
 
+function truncateWidth(value, max) {
+  const text = String(value || "");
+  if (visWidth(text) <= max) return text;
+  let out = "";
+  let width = 0;
+  const room = Math.max(0, max - 1);
+  for (const ch of text) {
+    const cells = charWidth(ch);
+    if (width + cells > room) break;
+    out += ch;
+    width += cells;
+  }
+  return out + "…";
+}
+
+function identityPalette() {
+  const id = (value) => String(value);
+  return { faint: id, emerald: id, text: id, paw: id, amber: id, blue: id, dim: id, inverse: id };
+}
+
+function permissionPresentation(ctx, c) {
+  const permission = permissions.normalize(ctx.permission, "write");
+  const fallback = permissions.copy(permission, ctx.lang || "en").label;
+  const label = ctx.permissionLabel || fallback;
+  if (permission === "full") return c.paw("▶▶ " + label);
+  if (permission === "read") return c.blue("◇ " + label);
+  return c.amber("◆ " + label);
+}
+
+// Pure frame builder so layout can be regression-tested without taking over a real TTY.
+function buildComposerFrame(state, ctx = {}, palette, width = 80) {
+  const c = palette || identityPalette();
+  const w = Math.max(29, width);
+  const fieldW = Math.max(8, w - 2);
+
+  // horizontal scroll by visual width — keep the cursor visible (CJK-safe)
+  let start = Math.min(state.scroll, state.cur);
+  while (start < state.cur && visWidth(state.buf.slice(start, state.cur)) > fieldW - 2) start++;
+  state.scroll = start;
+
+  let shown = "";
+  let shownWidth = 0;
+  for (let i = start; i < state.buf.length; ) {
+    const ch = state.buf.codePointAt(i) > 0xffff ? state.buf.slice(i, i + 2) : state.buf[i];
+    const cw = charWidth(ch);
+    if (shownWidth + cw > fieldW - 2) break;
+    shown += ch;
+    shownWidth += cw;
+    i += ch.length;
+  }
+
+  const prefix = (ctx.glyph || "›") + " ";
+  const top = c.faint("─".repeat(w));
+  const mid = c.text(prefix) + c.text(shown);
+  const bot = c.faint("─".repeat(w));
+  const lines = [top, mid, bot];
+  if (ctx.status || ctx.permission) {
+    const permission = permissions.normalize(ctx.permission, "write");
+    const fallback = permissions.copy(permission, ctx.lang || "en").label;
+    const permissionLabel = ctx.permissionLabel || fallback;
+    const permissionText = (permission === "full" ? "▶▶ " : permission === "read" ? "◇ " : "◆ ") + permissionLabel;
+    const available = Math.max(0, w - visWidth(permissionText) - 5);
+    const rest = ctx.status && available > 0 ? c.faint("  ·  " + truncateWidth(ctx.status, available)) : "";
+    lines.push(permissionPresentation(ctx, c) + rest);
+  }
+  // 연결 LLM 세션 사용량 상시 표시줄 — 입력박스 바로 아래에 항상 유지된다.
+  const usageText = typeof ctx.usage === "function" ? ctx.usage() : ctx.usage;
+  if (usageText) lines.push(c.faint(truncateWidth(String(usageText), w)));
+  if (ctx.confirmation) {
+    const prefix = ctx.confirmationTone === "danger" ? "! " : "✓ ";
+    const paint = ctx.confirmationTone === "danger" && c.paw ? c.paw : c.green || c.emerald || ((value) => value);
+    lines.push(paint(truncateWidth(prefix + ctx.confirmation, w)));
+  }
+
+  const rows = state.suggest || [];
+  rows.slice(0, 8).forEach((row, index) => {
+    const cmd = String(row.command || "").padEnd(16);
+    const desc = String(row.description || "");
+    const descRoom = Math.max(0, w - visWidth(" " + cmd + " "));
+    const clippedDesc = truncateWidth(desc, descRoom);
+    const label = " " + cmd + " " + clippedDesc;
+    lines.push(index === state.suggestSel ? c.inverse(label) : " " + c.blue(cmd) + " " + c.dim(clippedDesc));
+  });
+  if (rows.length) lines.push(c.faint("  " + i18n.t(ctx.lang || "en", "palette.controls")));
+
+  return { lines, curCol: visWidth(prefix) + visWidth(state.buf.slice(start, state.cur)) };
+}
+
 function createComposer(opts) {
   const out = opts.stream || process.stdout;
   const inp = opts.input || process.stdin;
@@ -61,45 +151,7 @@ function createComposer(opts) {
 
   // Build the rendered block (array of lines) + the cursor target column on the input line.
   function frame(state, ctx) {
-    const w = boxWidth();
-    const inner = w - 2; // chars between │ … │
-    const glyph = " " + (ctx.glyph || "›") + " "; // " › "
-    const glyphW = visWidth(glyph);
-    const fieldW = Math.max(8, inner - glyphW);
-
-    // horizontal scroll by visual width — keep the cursor visible (CJK-safe)
-    let start = Math.min(state.scroll, state.cur);
-    while (start < state.cur && visWidth(state.buf.slice(start, state.cur)) > fieldW - 1) start++;
-    state.scroll = start;
-
-    let shown = "";
-    let ww = 0;
-    for (let i = start; i < state.buf.length; ) {
-      const ch = state.buf.codePointAt(i) > 0xffff ? state.buf.slice(i, i + 2) : state.buf[i];
-      const cw = charWidth(ch);
-      if (ww + cw > fieldW) break;
-      shown += ch;
-      ww += cw;
-      i += ch.length;
-    }
-    const pad = " ".repeat(Math.max(0, fieldW - ww));
-    const top = c.faint("╭" + "─".repeat(inner) + "╮");
-    const mid = c.faint("│") + c.emerald(glyph) + c.text(shown) + pad + c.faint("│");
-    const bot = c.faint("╰" + "─".repeat(inner) + "╯");
-    const lines = [top, mid, bot];
-    if (ctx.status) lines.push("  " + c.faint(ctx.status));
-
-    const rows = state.suggest || [];
-    rows.slice(0, 8).forEach((r, i) => {
-      const cmd = String(r.command || "").padEnd(16);
-      const desc = String(r.description || "");
-      const label = (" " + cmd + " " + desc).slice(0, w);
-      lines.push(i === state.suggestSel ? c.inverse(label) : " " + c.blue(cmd) + c.dim(desc.slice(0, w - 20)));
-    });
-    if (rows.length) lines.push(c.faint("  ↑↓ move · Tab complete · Enter run · Esc close"));
-
-    const curCol = 1 + glyphW + visWidth(state.buf.slice(start, state.cur)); // 0-based visual column
-    return { lines, curCol };
+    return buildComposerFrame(state, ctx, c, boxWidth());
   }
 
   function render(state, ctx) {
@@ -172,6 +224,14 @@ function createComposer(opts) {
       function onKey(str, key) {
         key = key || {};
         const name = key.name;
+        const shiftTab = name === "tab" && key.shift;
+
+        if (!shiftTab && ctx.onPermissionCycleCancel) {
+          const hadConfirmation = Boolean(ctx.confirmation);
+          const next = ctx.onPermissionCycleCancel();
+          if (next && typeof next === "object") Object.assign(ctx, next);
+          if (hadConfirmation && !ctx.confirmation) draw();
+        }
 
         if (key.ctrl && name === "c") {
           if (state.buf.length) { ctrlc = 0; return setBuf("", 0); }
@@ -212,6 +272,14 @@ function createComposer(opts) {
           if (state.suggest.length) { state.suggestSel = (state.suggestSel + 1) % state.suggest.length; state.buf = state.suggest[state.suggestSel].command; state.cur = state.buf.length; return render(state, ctx); }
           return histNav(-1);
         }
+        if (shiftTab) {
+          if (ctx.onCyclePermission) {
+            const next = ctx.onCyclePermission(ctx.permission);
+            if (next && typeof next === "object") Object.assign(ctx, next);
+            draw();
+          }
+          return;
+        }
         if (name === "tab") {
           if (state.suggest.length) { const cmd = state.suggest[state.suggestSel].command; state.dismissed = cmd; return setBuf(cmd, cmd.length); }
           if (ctx.complete) {
@@ -253,4 +321,4 @@ function createComposer(opts) {
   return { read, setHistory: (h) => { history = (h || []).filter((x) => typeof x === "string"); } };
 }
 
-module.exports = { createComposer, visWidth };
+module.exports = { createComposer, visWidth, buildComposerFrame, truncateWidth };