pleumrouter 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,133 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may only
+distribute the software according to Distribution License
+and make changes or new works based on the software
+according to Changes and New Works License.
+
+Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license to
+distribute covers distributing the software with changes
+and new works permitted by Changes and New Works License.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with Required Notice: that the licensor provided
+with the software. For example:
+
+Required Notice: Copyright 2026 Lee Wonyoung (https://github.com/gachon-star-want/PleumRouter)
+
+Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, or will
+be able to license, that you would infringe by using the
+software.
+
+Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or
+religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your employer makes such a claim, your patent license ends
+immediately for work on behalf of your employer.
+
+Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into compliance within 32 days after
+receiving notice. Otherwise, all your licenses end permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.
+
+Definitions
+
+The licensor is the individual or entity offering these
+terms, and the software is the software the licensor makes
+available under these terms.
+
+You refers to the individual or entity agreeing to these
+terms.
+
+Your company is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. Control
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and legal affairs.
+
+Your licenses are all the licenses granted to you for the
+software under these terms.
+
+Use means anything you do with the software requiring one
+of your licenses.
+
+Trademark
+
+The PolyForm Noncommercial License 1.0.0 does not grant
+any rights to use the licensor's trademarks, trade names,
+or logos.

package/README.md

@@ -7,17 +7,42 @@ npx pleumrouter login                          # 브라우저 로그인 + 키
 npx pleumrouter launch claude --model claude-sonnet-4
 npx pleumrouter launch codex  --model gpt-4.1
 npx pleumrouter run gpt-4.1                     # 터미널 채팅
+npx pleumrouter run gpt-4.1 "한 줄 요약: ..."   # 1회 실행(스크립트용)
+cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 ```
 
 ## 명령
 
 | 명령 | 설명 |
 |------|------|
-| `pleum login` | 브라우저로 로그인 → CLI가 API 키를 자동 발급·저장(`~/.pleum/config.json`) |
+| `pleum login [--device]` | 브라우저로 로그인 → CLI가 API 키를 자동 발급·저장(`~/.pleum/config.json`). `--device`는 SSH·CI |
 | `pleum logout` | 저장된 키 삭제 |
-| `pleum launch <tool> [--model id] [-- args]` | 에이전트 실행. `--` 뒤 인자는 도구로 그대로 전달 |
-| `pleum run <model>` | 스트리밍 채팅 REPL |
-| `pleum models [query]` | 모델 목록(공개) |
+| `pleum launch [tool] [--model id] [-- args]` | 에이전트 실행. `--` 뒤 인자는 도구로 그대로 전달. 도구 생략 시 지원 목록·설치 여부 표시 |
+| `pleum run [model] ["프롬프트"]` | 채팅 — 대화형 REPL, 1회 실행, stdin 파이프. 모델 생략 시 인터랙티브 선택 |
+| `pleum models [query] [--json]` | 모델 목록(공개) — provider·컨텍스트·가격(₩/1M) 컬럼, `--json`은 스크립트용 |
+| `pleum balance` | 크레딧 잔액 조회 |
+| `pleum completion <zsh\|bash>` | 셸 자동완성 스크립트 출력 |
+| `pleum upgrade` | 최신 버전으로 재설치 |
+| `pleum version` | 버전 출력 |
+
+## 채팅 REPL 명령
+
+`pleum run` 안에서:
+
+| 명령 | 설명 |
+|------|------|
+| `/help`, `/?` | 명령 도움말 |
+| `/model [id]` | **세션 유지한 채 모델 전환**(여러 모델을 한 대화에서 비교) |
+| `/system [텍스트]` | 시스템 프롬프트 설정/확인 |
+| `/clear` | 대화 컨텍스트 초기화 |
+| `/models [검색어]` | 모델 목록 보기 |
+| `/save [이름]`, `/load [이름]` | 세션 저장·복원(`~/.pleum/sessions/`) |
+| `/verbose` | 토큰·속도 통계 토글 |
+| `/exit`, `/quit` | 종료 |
+
+- 여러 줄 입력: `"""` 한 줄 → 본문 → `"""` 한 줄
+- 이미지: 메시지에 이미지 파일 경로를 그대로 포함 (예: `이 그림 설명해줘 ./shot.png`)
+- `↑` 로 지난 입력 재호출(히스토리는 `~/.pleum/history`에 영속)
 
 ## 자동 실행 지원 도구
 

package/bin/pleum.mjs

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { login, loginDevice } from "../src/login.mjs";
-import { launch } from "../src/launch.mjs";
+import { launch, launchHelp } from "../src/launch.mjs";
 import { run } from "../src/run.mjs";
 import { listModels } from "../src/models.mjs";
 import { balance } from "../src/balance.mjs";
+import { completion } from "../src/completion.mjs";
+import { upgrade } from "../src/upgrade.mjs";
 import { clearConfig } from "../src/config.mjs";
 
 const HELP = `pleum — PleumRouter 터미널 CLI
@@ -11,17 +14,24 @@ const HELP = `pleum — PleumRouter 터미널 CLI
   pleum login [--device]             브라우저로 로그인 + 키 자동 저장
                                      --device: 브라우저 없는 환경(SSH·CI)
   pleum logout                       저장된 키 삭제
-  pleum launch <tool> [--model id]   코딩 에이전트를 PleumRouter로 실행
+  pleum launch [tool] [--model id]   코딩 에이전트를 PleumRouter로 실행
                                      (claude · aider · codex · goose · openhands)
-  pleum run <model>                  터미널 채팅
-  pleum models [query]               모델 목록
+                                     도구 생략 시 지원 목록·설치 여부 표시
+  pleum run [model] ["프롬프트"]      터미널 채팅(REPL) / 1회 실행 / 파이프
+                                     모델 생략 시 인터랙티브 선택, /help 로 명령
+  pleum models [query] [--json]      모델 목록(가격·컨텍스트 포함)
   pleum balance                      크레딧 잔액 조회
+  pleum completion <zsh|bash>        셸 자동완성 스크립트 출력
+  pleum upgrade                      최신 버전으로 재설치
+  pleum version                      버전 출력
 
 예:
   pleum launch claude --model claude-sonnet-4
   pleum launch codex --model gpt-4.1 -- --full-auto
-  pleum run gpt-4.1
-  pleum login --device               # SSH/CI 환경
+  pleum run gpt-4.1                          # 대화형
+  pleum run gpt-4.1 "한 줄로 요약: ..."       # 1회 실행
+  cat error.log | pleum run gpt-4.1 "원인은?"  # 파이프
+  pleum login --device                       # SSH/CI 환경
 
 base_url 덮어쓰기: PLEUM_BASE_URL 환경변수`;
 
@@ -38,6 +48,11 @@ function parseLaunchArgs(args) {
   return out;
 }
 
+function version() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  console.log(`pleum ${pkg.version}`);
+}
+
 const [cmd, ...rest] = process.argv.slice(2);
 
 try {
@@ -53,22 +68,33 @@ try {
     case "launch": {
       const tool = rest[0];
       if (!tool) {
-        console.error("사용법: pleum launch <tool> [--model id]");
-        process.exit(1);
+        launchHelp();
+        break;
       }
       const { model, passthrough } = parseLaunchArgs(rest.slice(1));
       await launch(tool, model, passthrough);
       break;
     }
     case "run":
-      await run(rest[0]);
+      await run(rest);
       break;
     case "models":
-      await listModels(rest[0]);
+      await listModels(rest);
       break;
     case "balance":
       await balance();
       break;
+    case "completion":
+      completion(rest[0]);
+      break;
+    case "upgrade":
+      upgrade();
+      break;
+    case "version":
+    case "-v":
+    case "--version":
+      version();
+      break;
     case undefined:
     case "-h":
     case "--help":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pleumrouter",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Official PleumRouter terminal CLI — launch any coding agent against PleumRouter.",
   "type": "module",
   "bin": {
@@ -12,16 +12,25 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node --test"
   },
-  "license": "MIT",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["pleum", "ai", "llm", "openai", "claude", "coding-agent", "cli"],
+  "keywords": [
+    "pleum",
+    "ai",
+    "llm",
+    "openai",
+    "claude",
+    "coding-agent",
+    "cli"
+  ],
   "homepage": "https://router.pleum.ai/docs/cli",
   "repository": {
     "type": "git",

package/src/completion.mjs

@@ -0,0 +1,47 @@
+// Shell 자동완성 스크립트 출력. 명령·도구는 정적, 모델명은 `pleum models`에서 동적으로 채운다.
+// 설치: pleum completion zsh >> ~/.zshrc  ·  pleum completion bash >> ~/.bashrc
+const COMMANDS = "login logout launch run models balance version upgrade completion help";
+const TOOLS = "claude aider codex goose openhands opencode crush";
+
+function bash() {
+  return `# pleum bash completion — eval "$(pleum completion bash)" 또는 ~/.bashrc에 추가
+_pleum() {
+  local cur prev; cur="\${COMP_WORDS[COMP_CWORD]}"; prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${COMMANDS}" -- "$cur") ); return
+  fi
+  case "$prev" in
+    launch)     COMPREPLY=( $(compgen -W "${TOOLS}" -- "$cur") );;
+    run)        COMPREPLY=( $(compgen -W "$(pleum models 2>/dev/null | awk 'NR>1{print $1}')" -- "$cur") );;
+    completion) COMPREPLY=( $(compgen -W "zsh bash" -- "$cur") );;
+  esac
+}
+complete -F _pleum pleum`;
+}
+
+function zsh() {
+  return `#compdef pleum
+# pleum zsh completion — eval "$(pleum completion zsh)" 또는 fpath에 _pleum로 추가
+_pleum() {
+  if (( CURRENT == 2 )); then
+    compadd ${COMMANDS}; return
+  fi
+  case \${words[2]} in
+    launch)     compadd ${TOOLS};;
+    run)        compadd \${(f)"$(pleum models 2>/dev/null | awk 'NR>1{print \$1}')"};;
+    completion) compadd zsh bash;;
+  esac
+}
+_pleum "$@"`;
+}
+
+export function completion(shell) {
+  if (shell === "bash") return void console.log(bash());
+  if (shell === "zsh") return void console.log(zsh());
+  console.error(
+    "사용법: pleum completion <zsh|bash>\n" +
+      '  zsh:  eval "$(pleum completion zsh)"   (또는 ~/.zshrc에 추가)\n' +
+      '  bash: eval "$(pleum completion bash)"  (또는 ~/.bashrc에 추가)',
+  );
+  process.exit(1);
+}

package/src/config.mjs

@@ -9,6 +9,9 @@ export const V1 = `${ROOT}/v1`;
 
 const DIR = join(homedir(), ".pleum");
 const FILE = join(DIR, "config.json");
+// run REPL용 — 명령 히스토리 영속 + 세션 저장.
+export const HISTORY_FILE = join(DIR, "history");
+export const SESSIONS_DIR = join(DIR, "sessions");
 
 export function readConfig() {
   try {

package/src/launch.mjs

@@ -1,10 +1,33 @@
 import { spawn } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, delimiter } from "node:path";
 import { requireKey } from "./config.mjs";
 import { RECIPES, MANUAL, codexToml } from "./recipes.mjs";
 
+// PATH에서 실행 파일을 찾는다(설치 여부 표시용).
+function onPath(bin) {
+  const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  return (process.env.PATH || "")
+    .split(delimiter)
+    .some((d) => d && exts.some((e) => existsSync(join(d, bin + e))));
+}
+
+// `pleum launch`(도구 미지정) — 지원 도구 + 설치 여부를 안내.
+export function launchHelp() {
+  console.log("사용법: pleum launch <tool> [--model id] [-- 도구인자]\n");
+  console.log("자동 실행:");
+  for (const [name, r] of Object.entries(RECIPES)) {
+    const ok = onPath(r.bin) ? "✓ 설치됨" : `✗ 미설치 — ${r.install}`;
+    console.log(`  ${name.padEnd(11)} ${r.label.padEnd(13)} ${ok}`);
+  }
+  console.log("\n설정 안내(provider 정의 파일 필요):");
+  for (const [name, m] of Object.entries(MANUAL)) {
+    console.log(`  ${name.padEnd(11)} ${m.label}`);
+  }
+  console.log("\n예: pleum launch claude --model claude-sonnet-4");
+}
+
 export async function launch(tool, model, passthrough) {
   const key = requireKey();
   const r = RECIPES[tool];

package/src/models.mjs

@@ -8,19 +8,75 @@ export async function fetchModels() {
   return data.data ?? [];
 }
 
-export async function listModels(query) {
+// 컨텍스트 길이를 사람이 읽기 좋게: 128000→128K, 1000000→1M.
+export function fmtCtx(n) {
+  if (!n) return "—";
+  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1000) return `${Math.round(n / 1000)}K`;
+  return String(n);
+}
+
+// pricing(_krw)는 토큰당 단가 문자열. 1M 토큰당으로 환산해 표시(KRW 우선, 없으면 USD).
+export function fmtPrice(model) {
+  const per1m = (v, sym) => {
+    if (v == null) return "—";
+    const n = Number(v) * 1_000_000;
+    if (!Number.isFinite(n)) return "—";
+    return sym === "₩" ? `₩${Math.round(n).toLocaleString("en-US")}` : `$${n.toFixed(2)}`;
+  };
+  const kr = model.pricing_krw || {};
+  if (kr.prompt != null || kr.completion != null) return [per1m(kr.prompt, "₩"), per1m(kr.completion, "₩")];
+  const us = model.pricing || {};
+  if (us.prompt != null || us.completion != null) return [per1m(us.prompt, "$"), per1m(us.completion, "$")];
+  return ["—", "—"];
+}
+
+// 정렬된 컬럼 테이블 — 라우터의 강점(수백 모델·가격·컨텍스트)을 한눈에.
+export function formatTable(models) {
+  const headers = ["MODEL", "PROVIDER", "MODAL", "CTX", "IN/1M", "OUT/1M"];
+  const rows = models.map((m) => {
+    const [pin, pout] = fmtPrice(m);
+    return [
+      m.id,
+      m.provider || "",
+      m.modality || "text",
+      fmtCtx(m.context_length || m.context_window),
+      pin,
+      pout,
+    ];
+  });
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const fmt = (r) => r.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  return [fmt(headers), ...rows.map(fmt)].join("\n");
+}
+
+// `pleum models [query] [--json]` 인자 파싱.
+export function parseModelsArgs(rest = []) {
+  let json = false;
+  const pos = [];
+  for (const a of rest) {
+    if (a === "--json") json = true;
+    else pos.push(a);
+  }
+  return { json, query: pos[0] };
+}
+
+export async function listModels(rest) {
+  // 하위호환: 문자열 하나가 와도 query로 처리.
+  const { json, query } = Array.isArray(rest) ? parseModelsArgs(rest) : { json: false, query: rest };
   const models = await fetchModels();
   const q = (query || "").toLowerCase();
   const rows = models.filter(
-    (m) =>
-      !q ||
-      m.id.toLowerCase().includes(q) ||
-      (m.display_name || "").toLowerCase().includes(q),
+    (m) => !q || m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
   );
-  for (const m of rows) {
-    const parts = [m.id, m.modality || "text"];
-    if (m.display_name) parts.push(m.display_name);
-    console.log(parts.join("\t"));
+  if (json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (!rows.length) {
+    console.log("일치하는 모델 없음");
+    return;
   }
-  console.log(`\n${rows.length} models`);
+  console.log(formatTable(rows));
+  console.log(`\n${rows.length} models · 가격=토큰 1M당(표시환율 기준, 실청구는 장중 환율로 소폭 상이)`);
 }

package/src/run.mjs

@@ -1,60 +1,272 @@
 import { createInterface } from "node:readline";
-import { V1, requireKey } from "./config.mjs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { V1, requireKey, HISTORY_FILE, SESSIONS_DIR } from "./config.mjs";
+import { fetchModels, formatTable } from "./models.mjs";
 
-// 터미널 채팅 REPL — /v1/chat/completions 스트리밍을 토큰 단위로 출력.
-export async function run(model) {
+const IMG_EXT = /\.(png|jpe?g|gif|webp|bmp)$/i;
+
+// `pleum run [model] ["프롬프트"...] [--verbose]` 인자 파싱(순수 함수 — 테스트 대상).
+export function parseRunArgs(rest = []) {
+  let verbose = false;
+  const pos = [];
+  for (const a of rest) {
+    if (a === "--verbose" || a === "-v") verbose = true;
+    else pos.push(a);
+  }
+  return { model: pos[0], prompt: pos.slice(1).join(" "), verbose };
+}
+
+// 입력에서 존재하는 이미지 파일 경로를 찾아 멀티모달 content로 만든다(없으면 문자열 그대로).
+// exists/read 주입 가능 — 테스트용.
+export function buildContent(text, exists = existsSync, read = readFileSync) {
+  const imgs = text.split(/\s+/).filter((t) => IMG_EXT.test(t) && exists(t));
+  if (!imgs.length) return text;
+  const parts = [{ type: "text", text }];
+  for (const p of imgs) {
+    const ext = p.match(IMG_EXT)[1].toLowerCase().replace("jpg", "jpeg");
+    const b64 = Buffer.from(read(p)).toString("base64");
+    parts.push({ type: "image_url", image_url: { url: `data:image/${ext};base64,${b64}` } });
+  }
+  return parts;
+}
+
+// 응답 후 한 줄 통계(순수 함수 — 테스트 대상). verbose일 때만 토큰/속도 표시.
+export function formatStats({ cost, usage, ms, tokPerSec, verbose }) {
+  const bits = [];
+  if (cost) bits.push(`₩${cost}`);
+  if (verbose && usage) {
+    bits.push(`↑${usage.prompt_tokens ?? "?"} ↓${usage.completion_tokens ?? "?"} tok`);
+    if (tokPerSec) bits.push(`${tokPerSec.toFixed(1)} tok/s`);
+  }
+  if (verbose) bits.push(`${ms}ms`);
+  return bits.length ? `  (${bits.join(" · ")})` : "";
+}
+
+export async function run(rest) {
+  const args = Array.isArray(rest) ? rest : rest == null ? [] : [rest];
+  const { verbose, prompt: inlinePrompt, model: argModel } = parseRunArgs(args);
+  let model = argModel;
+  const piped = await readStdin();
+  const oneShot = Boolean(inlinePrompt || piped);
+  const key = requireKey();
+
+  if (!model && !oneShot) {
+    model = await pickModel(); // 인터랙티브 모델 선택
+    if (!model) process.exit(1);
+  }
   if (!model) {
-    console.error("사용법: pleum run <model>\n모델 목록: pleum models");
+    console.error('사용법: pleum run <model> ["프롬프트"]\n모델 목록: pleum models');
     process.exit(1);
   }
-  const key = requireKey();
-  const messages = [];
-  const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: "you> " });
 
-  console.log(`PleumRouter · ${model} · /exit 로 종료\n`);
+  if (oneShot) {
+    const prompt = [inlinePrompt, piped].filter(Boolean).join("\n\n");
+    const messages = [{ role: "user", content: buildContent(prompt) }];
+    try {
+      await streamChat(key, model, messages, { verbose, quiet: true });
+    } catch (e) {
+      console.error(`✗ ${e.message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  await repl(key, model, verbose);
+}
+
+async function repl(key, model, verbose) {
+  let system = "";
+  let messages = [];
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "you> ",
+    history: loadHistory(),
+    historySize: 1000,
+  });
+  let multiline = null; // """ 펜스 진행 중이면 누적 배열
+
+  console.log(`PleumRouter · ${model}\n/help 으로 명령, /exit 로 종료. 여러 줄은 """ 로 감싸기.\n`);
   rl.prompt();
 
+  const send = async (text) => {
+    messages.push({ role: "user", content: buildContent(text) });
+    const req = system ? [{ role: "system", content: system }, ...messages] : messages;
+    try {
+      const reply = await streamChat(key, model, req, { verbose });
+      messages.push({ role: "assistant", content: reply });
+    } catch (e) {
+      console.error(`\n✗ ${e.message}`);
+      messages.pop(); // 실패한 user 턴 제거
+    }
+  };
+
   rl.on("line", async (line) => {
+    if (multiline !== null) {
+      if (line.trim() === '"""') {
+        const text = multiline.join("\n");
+        multiline = null;
+        if (text.trim()) await send(text);
+      } else {
+        multiline.push(line);
+      }
+      rl.prompt();
+      return;
+    }
     const text = line.trim();
     if (text === "/exit" || text === "/quit") {
       rl.close();
       return;
     }
-    if (!text) {
+    if (text === '"""') {
+      multiline = [];
       rl.prompt();
       return;
     }
-    messages.push({ role: "user", content: text });
-    try {
-      const reply = await streamChat(key, model, messages);
-      messages.push({ role: "assistant", content: reply });
-    } catch (e) {
-      console.error(`\n✗ ${e.message}`);
-      messages.pop(); // 실패한 user 턴은 히스토리에서 제거
+    if (text.startsWith("/")) {
+      await handleSlash(text, {
+        get model() {
+          return model;
+        },
+        set model(m) {
+          model = m;
+        },
+        get system() {
+          return system;
+        },
+        set system(s) {
+          system = s;
+        },
+        get verbose() {
+          return verbose;
+        },
+        set verbose(v) {
+          verbose = v;
+        },
+        clear: () => {
+          messages = [];
+        },
+        snapshot: () => ({ model, system, messages }),
+        restore: (s) => {
+          model = s.model ?? model;
+          system = s.system ?? "";
+          messages = s.messages ?? [];
+        },
+      });
+      rl.prompt();
+      return;
+    }
+    if (!text) {
+      rl.prompt();
+      return;
     }
+    await send(text);
     rl.prompt();
   });
 
   rl.on("close", () => {
+    saveHistory(rl.history);
     console.log("\n안녕히 가세요.");
     process.exit(0);
   });
 }
 
-async function streamChat(key, model, messages) {
+const SLASH_HELP = `명령:
+  /help, /?           이 도움말
+  /clear              대화 컨텍스트 초기화(시스템 프롬프트는 유지)
+  /system [텍스트]    시스템 프롬프트 설정(인자 없으면 현재값 표시)
+  /model [id]         세션 유지한 채 모델 전환(인자 없으면 현재 모델)
+  /models [검색어]    모델 목록 보기
+  /save [이름]        현재 세션 저장(기본 last)
+  /load [이름]        세션 불러오기
+  /verbose            토큰·속도 통계 표시 토글
+  /exit, /quit        종료
+  여러 줄 입력: """ 한 줄 → 본문 → """ 한 줄
+  이미지: 메시지에 이미지 파일 경로를 그대로 포함(예: 이 그림 설명해줘 ./shot.png)`;
+
+async function handleSlash(text, ctx) {
+  const [cmd, ...rest] = text.slice(1).split(/\s+/);
+  const arg = text.slice(1 + cmd.length).trim();
+  switch (cmd) {
+    case "help":
+    case "?":
+      console.log(SLASH_HELP);
+      break;
+    case "clear":
+      ctx.clear();
+      console.log("✓ 컨텍스트 초기화");
+      break;
+    case "system":
+      if (arg) {
+        ctx.system = arg;
+        console.log("✓ 시스템 프롬프트 설정");
+      } else {
+        console.log(ctx.system ? `현재 시스템 프롬프트:\n${ctx.system}` : "시스템 프롬프트 없음");
+      }
+      break;
+    case "model":
+      if (arg) {
+        ctx.model = arg;
+        console.log(`✓ 모델 전환 → ${arg}`);
+      } else {
+        console.log(`현재 모델: ${ctx.model}\n전환: /model <id>  ·  목록: /models`);
+      }
+      break;
+    case "models":
+      try {
+        const models = await fetchModels();
+        const q = arg.toLowerCase();
+        const rows = models.filter(
+          (m) => !q || m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
+        );
+        console.log(rows.length ? formatTable(rows) : "일치하는 모델 없음");
+      } catch (e) {
+        console.error(`✗ ${e.message}`);
+      }
+      break;
+    case "save":
+      try {
+        const name = saveSession(arg || "last", ctx.snapshot());
+        console.log(`✓ 세션 저장: ${name}`);
+      } catch (e) {
+        console.error(`✗ 저장 실패: ${e.message}`);
+      }
+      break;
+    case "load":
+      try {
+        ctx.restore(loadSession(arg || "last"));
+        console.log(`✓ 세션 불러옴 (모델: ${ctx.model})`);
+      } catch {
+        console.error(`✗ 세션 없음: ${arg || "last"}`);
+      }
+      break;
+    case "verbose":
+      ctx.verbose = !ctx.verbose;
+      console.log(`✓ 통계 ${ctx.verbose ? "켜짐" : "꺼짐"}`);
+      break;
+    default:
+      console.log(`알 수 없는 명령: /${cmd}  (/help)`);
+  }
+}
+
+async function streamChat(key, model, messages, { verbose = false, quiet = false } = {}) {
+  const t0 = Date.now();
   const res = await fetch(`${V1}/chat/completions`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ model, messages, stream: true }),
+    body: JSON.stringify({ model, messages, stream: true, stream_options: { include_usage: true } }),
   });
   if (!res.ok) {
     const body = await res.text().catch(() => "");
     throw new Error(`${res.status} ${body.slice(0, 300)}`);
   }
 
-  process.stdout.write("bot> ");
+  if (!quiet) process.stdout.write("bot> ");
   let full = "";
   let buf = "";
+  let usage = null;
+  let firstAt = 0;
   const decoder = new TextDecoder();
   for await (const chunk of res.body) {
     buf += decoder.decode(chunk, { stream: true });
@@ -66,8 +278,11 @@ async function streamChat(key, model, messages) {
       const data = s.slice(5).trim();
       if (data === "[DONE]") continue;
       try {
-        const delta = JSON.parse(data).choices?.[0]?.delta?.content;
+        const j = JSON.parse(data);
+        if (j.usage) usage = j.usage;
+        const delta = j.choices?.[0]?.delta?.content;
         if (delta) {
+          if (!firstAt) firstAt = Date.now();
           process.stdout.write(delta);
           full += delta;
         }
@@ -77,7 +292,94 @@ async function streamChat(key, model, messages) {
     }
   }
   process.stdout.write("\n");
+
+  const ms = Date.now() - t0;
+  const genSec = (Date.now() - (firstAt || t0)) / 1000;
+  const tokPerSec = usage?.completion_tokens && genSec > 0 ? usage.completion_tokens / genSec : null;
   const cost = res.headers.get("x-cost-krw");
-  if (cost) console.log(`  (₩${cost})`);
+  // 파이프 출력(quiet)은 stdout을 깨끗이 — 통계는 verbose일 때만 stderr로.
+  const line = formatStats({ cost: quiet ? null : cost, usage, ms, tokPerSec, verbose });
+  if (line) (quiet ? console.error : console.log)(line);
+  else if (quiet && verbose && cost) console.error(`  (₩${cost})`);
   return full;
 }
+
+// ── 인터랙티브 모델 피커 ──────────────────────────────────────────────
+// 번호 선택 + 검색어 좁히기. ponytail: 화살표 raw-mode는 후속(SSH/파이프 엣지케이스 회피).
+async function pickModel() {
+  let models;
+  try {
+    models = await fetchModels();
+  } catch (e) {
+    console.error(`✗ 모델 목록 조회 실패: ${e.message}`);
+    return null;
+  }
+  if (!models.length) return null;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((r) => rl.question(q, r));
+  let pool = models;
+  try {
+    for (;;) {
+      const shown = pool.slice(0, 30);
+      shown.forEach((m, i) =>
+        console.log(`  ${String(i + 1).padStart(2)}. ${m.id}${m.display_name ? `  (${m.display_name})` : ""}`),
+      );
+      if (pool.length > shown.length) console.log(`  … ${pool.length - shown.length}개 더 — 검색어로 좁히기`);
+      const ans = (await ask("\n번호 선택 또는 검색어 (Enter=취소): ")).trim();
+      if (!ans) return null;
+      const n = Number(ans);
+      if (Number.isInteger(n) && n >= 1 && n <= shown.length) return shown[n - 1].id;
+      const q = ans.toLowerCase();
+      const next = models.filter(
+        (m) => m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
+      );
+      pool = next.length ? next : models;
+      if (!next.length) console.log("일치 없음 — 전체 목록으로.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// ── 히스토리 / 세션 영속 ──────────────────────────────────────────────
+function loadHistory() {
+  // readline history는 최신이 앞(역순). 파일은 시간순으로 저장한다.
+  try {
+    return readFileSync(HISTORY_FILE, "utf8").split("\n").filter(Boolean).reverse();
+  } catch {
+    return [];
+  }
+}
+
+function saveHistory(history) {
+  try {
+    mkdirSync(SESSIONS_DIR, { recursive: true, mode: 0o700 }); // ~/.pleum 보장(SESSIONS_DIR 부모)
+    const chrono = (history || []).slice(0, 1000).reverse().join("\n");
+    writeFileSync(HISTORY_FILE, chrono, { mode: 0o600 });
+  } catch {
+    // 히스토리 저장 실패는 치명적 아님 — 무시
+  }
+}
+
+function sessionPath(name) {
+  return join(SESSIONS_DIR, `${name.replace(/[^\w.-]/g, "_")}.json`);
+}
+
+function saveSession(name, data) {
+  mkdirSync(SESSIONS_DIR, { recursive: true, mode: 0o700 });
+  const path = sessionPath(name);
+  writeFileSync(path, JSON.stringify(data, null, 2), { mode: 0o600 });
+  return path;
+}
+
+function loadSession(name) {
+  return JSON.parse(readFileSync(sessionPath(name), "utf8"));
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  let data = "";
+  process.stdin.setEncoding("utf8");
+  for await (const c of process.stdin) data += c;
+  return data.trim();
+}

package/src/upgrade.mjs

@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+
+// 최신 버전으로 전역 재설치. brew tap 보류 상태라 npm 경로([[project_pleum_cli]]).
+export function upgrade() {
+  console.log("▶ npm install -g pleumrouter@latest\n");
+  const child = spawn("npm", ["install", "-g", "pleumrouter@latest"], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  child.on("error", (e) => {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}