@sejuneoh/aitop 0.0.0-stage → 0.21.2

package/src/sources/codex.mjs

@@ -0,0 +1,374 @@
+// Codex CLI: 실행 중인 codex 프로세스의 작업 폴더와 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl 을 짝지어 읽는다.
+import { readdirSync, statSync, existsSync, realpathSync, openSync, readSync, closeSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { JsonlTail } from '../tail.mjs';
+import { loadCache, markDirty } from '../cache.mjs';
+import { findProcesses, isCodex, openFiles, processStart } from '../procs.mjs';
+import { addActivity, emptyTokens, parseTs, pushEvent, describeTool, isNoisePrompt } from './common.mjs';
+import { addChange, mergeFiles } from './files.mjs';
+import { codexCost } from '../pricing.mjs';
+import { parsePatch, extractPatch, patchSucceeded } from './patch.mjs';
+import { debug, debugIo } from '../log.mjs';
+
+// 지시 탭에 쓰는 지시 목록은 최근 것만 남긴다.
+const MAX_TURNS = 50;
+
+const ROOT = join(process.env.CODEX_HOME ?? join(homedir(), '.codex'), 'sessions');
+const RECENT_MS = 24 * 3600 * 1000;
+
+const states = new Map();
+
+export function dayDirs(days = 7) {
+  const dirs = [];
+  // 며칠 동안 켜 둔 세션도 시작한 날짜 폴더에 기록하므로 일주일치 폴더를 본다.
+  for (let back = 0; back < days; back++) {
+    const d = new Date(Date.now() - back * 86400_000);
+    const p = join(ROOT, String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0'));
+    if (existsSync(p)) dirs.push(p);
+  }
+  return dirs;
+}
+
+// 날짜 폴더를 매초 다시 훑지 않도록 파일 이름 목록만 잠깐 재사용한다. 수정 시각은 매번 확인한다.
+const LIST_TTL_MS = 5000;
+let listed = { at: 0, paths: [] };
+
+function recentFiles() {
+  if (Date.now() - listed.at >= LIST_TTL_MS) {
+    const paths = [];
+    for (const dir of dayDirs()) for (const n of readdirSync(dir)) if (n.endsWith('.jsonl')) paths.push(join(dir, n));
+    listed = { at: Date.now(), paths };
+  }
+  const out = [];
+  for (const p of listed.paths) {
+    let m;
+    try {
+      m = statSync(p).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (Date.now() - m < RECENT_MS) out.push({ path: p, mtime: m });
+  }
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+// 하루 넘게 쉰 세션은 최근 파일 목록에 없다. 짝을 못 찾은 codex 프로세스에만 같은 작업 폴더에서 가장 최근에
+// 바뀐 파일을 30일치 폴더에서 찾되, 프로세스가 시작한 뒤에 쓰인 파일만 받는다. 그래야 첫 입력 전인 새 codex 에
+// 지난 세션이 붙지 않는다. 시작 시각을 모르면 찾지 않는다.
+// 찾은 파일은 pid 별로 기억한다. 못 찾았으면 날짜 폴더가 바뀔 때(새 파일·새 폴더)까지만 다시 찾지 않는다.
+const OLD_DAYS = 30;
+const HEAD_BYTES = 256 * 1024;
+const cwdByPath = new Map();
+const foundByPid = new Map();
+let headBuf = null;
+
+// session_meta 첫 줄은 지침 글 때문에 길 수 있어 JSON 전체 대신 앞부분의 cwd 만 찾는다.
+function headCwd(path) {
+  if (cwdByPath.has(path)) return cwdByPath.get(path);
+  let cwd = null;
+  try {
+    const fd = openSync(path, 'r');
+    try {
+      headBuf ??= Buffer.alloc(HEAD_BYTES);
+      const m = /"cwd":("(?:[^"\\]|\\.)*")/.exec(headBuf.toString('utf8', 0, readSync(fd, headBuf, 0, HEAD_BYTES, 0)));
+      if (m) cwd = JSON.parse(m[1]);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (e) {
+    debugIo('codex', 'rollout head read failed', e, path);
+  }
+  cwdByPath.set(path, cwd);
+  return cwd;
+}
+
+let realRoot = null;
+
+function isRollout(p) {
+  if (realRoot === null) {
+    try {
+      realRoot = realpathSync(ROOT);
+    } catch (e) {
+      debugIo('codex', 'sessions realpath failed', e);
+    }
+  }
+  return (p.startsWith(ROOT + '/') || (realRoot !== null && p.startsWith(realRoot + '/'))) && /\/rollout-[^/]*\.jsonl$/.test(p);
+}
+
+// 날짜 폴더에 파일이 생기면 그 폴더의 수정 시각이 바뀐다.
+function foldersSignature(dirs) {
+  return dirs
+    .map((d) => {
+      try {
+        return d + ':' + statSync(d).mtimeMs;
+      } catch {
+        return d;
+      }
+    })
+    .join('|');
+}
+
+function latestFor(dirs, cwd, since, taken) {
+  let best = null;
+  const listed = new Set();
+  for (const dir of dirs) {
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch (e) {
+      debugIo('codex', 'day folder read failed', e, dir);
+      continue;
+    }
+    for (const n of names) {
+      const p = join(dir, n);
+      if (!n.endsWith('.jsonl')) continue;
+      listed.add(p);
+      if (taken.has(p)) continue;
+      let m;
+      try {
+        m = statSync(p).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (m >= since && (!best || m > best.mtime) && headCwd(p) === cwd) best = { path: p, mtime: m };
+    }
+  }
+  for (const p of cwdByPath.keys()) if (!listed.has(p)) cwdByPath.delete(p);
+  return best?.path ?? null;
+}
+
+function searchByCwd(pid, cwd, taken, startOf) {
+  const memo = foundByPid.get(pid);
+  if (memo?.path) return taken.has(memo.path) ? null : memo.path;
+  const dirs = dayDirs(OLD_DAYS);
+  const sig = foldersSignature(dirs);
+  if (memo && memo.sig === sig) return null;
+  const since = startOf(pid);
+  if (since === null) return null;
+  const path = latestFor(dirs, cwd, since, taken);
+  foundByPid.set(pid, { path, sig });
+  return path;
+}
+
+const SAVED = ['id', 'cwd', 'branch', 'model', 'busy', 'tokens', 'context', 'window', 'events', 'lastTool', 'startedAt', 'lastKind', 'files', 'turns', 'turnCount', 'activity'];
+
+function newState(path) {
+  const st = { tail: new JsonlTail(path), id: basename(path), cwd: null, branch: null, model: null, busy: false, tokens: emptyTokens(), context: 0, window: 0, events: [], lastTool: null, startedAt: null, pending: new Map(), lastKind: null, files: [], turns: [], turnCount: 0, patches: {}, activity: {} };
+  const c = loadCache(path);
+  if (c) {
+    st.tail.offset = c.offset;
+    for (const k of SAVED) if (k in c) st[k] = c[k];
+    st.pending = new Map(c.pending ?? []);
+  }
+  return st;
+}
+
+function snapshot(st) {
+  const out = { offset: st.tail.lineOffset, pending: [...st.pending] };
+  for (const k of SAVED) out[k] = st[k];
+  return out;
+}
+
+function phaseOf(st, live) {
+  if (!live) return { kind: 'ended', text: '종료' };
+  if (!st.busy) return { kind: 'idle', text: '다음 지시 대기' };
+  const open = [...st.pending.values()];
+  if (open.length) return { kind: 'tool', text: `도구 실행 · ${open.at(-1)}` };
+  return st.lastKind === 'reply' ? { kind: 'write', text: '답변 작성 중' } : { kind: 'think', text: '생각 중' };
+}
+
+function applyLine(st, x) {
+  const p = x.payload ?? {};
+  if (x.type === 'session_meta') {
+    st.id = p.id ?? st.id;
+    st.cwd = p.cwd ?? st.cwd;
+    st.branch = p.git?.branch ?? st.branch;
+    st.startedAt = Date.parse(p.timestamp) || st.startedAt;
+  } else if (x.type === 'turn_context') {
+    st.model = p.model ?? st.model;
+    st.cwd = p.cwd ?? st.cwd;
+  } else if (x.type === 'event_msg') {
+    switch (p.type) {
+      case 'task_started':
+        st.busy = true;
+        if (p.model_context_window) st.window = p.model_context_window;
+        break;
+      case 'task_complete':
+      case 'turn_aborted':
+        st.busy = false;
+        st.pending.clear();
+        st.patches = {};
+        break;
+      case 'token_count': {
+        const t = p.info?.total_token_usage;
+        if (t) {
+          const cached = t.cached_input_tokens ?? 0;
+          // 누적값이라 직전 합계와의 차이를 그 줄의 시각 칸에 더한다.
+          addActivity(st.activity, parseTs(x.timestamp), (t.total_tokens ?? 0) - st.tokens.total);
+          st.tokens = { input: (t.input_tokens ?? 0) - cached, output: t.output_tokens ?? 0, cacheRead: cached, cacheWrite: 0, total: t.total_tokens ?? 0 };
+        }
+        if (p.info?.last_token_usage) st.context = p.info.last_token_usage.total_tokens ?? 0;
+        if (p.info?.model_context_window) st.window = p.info.model_context_window;
+        break;
+      }
+      case 'user_message':
+        if (p.message && !isNoisePrompt(p.message)) {
+          const e = pushEvent(st, x.timestamp, 'prompt', p.message);
+          if (e) {
+            st.turns.push({ n: ++st.turnCount, at: e.at, text: e.text.slice(0, 120) });
+            if (st.turns.length > MAX_TURNS) st.turns.shift();
+          }
+        }
+        st.lastKind = 'prompt';
+        break;
+      case 'agent_message':
+        pushEvent(st, x.timestamp, 'reply', p.message);
+        st.lastKind = 'reply';
+        break;
+    }
+  } else if (x.type === 'response_item') {
+    let what = null;
+    if (p.type === 'function_call') {
+      let args = {};
+      try {
+        args = JSON.parse(p.arguments ?? '{}');
+      } catch (e) {
+        debug('codex', 'function_call arguments parse failed', e);
+      }
+      what = describeTool(p.name, args);
+      // 예전 Codex 는 apply_patch 를 shell 명령 인자로 보냈다 (["apply_patch", "*** Begin Patch…"] 또는 bash -lc 안의 글).
+      const cmd = Array.isArray(args.command) ? args.command.join('\n') : String(args.command ?? '');
+      const text = /\bapply_patch\b/.test(cmd) ? extractPatch(cmd) : null;
+      if (p.call_id && text) st.patches[p.call_id] = { at: x.timestamp, text };
+    } else if (p.type === 'custom_tool_call') {
+      what = describeTool(p.name, p.input ?? '');
+      if (p.call_id && p.name === 'apply_patch') st.patches[p.call_id] = { at: x.timestamp, text: String(p.input ?? '') };
+    } else if (p.type === 'web_search_call') what = 'WebSearch';
+    else if (p.type === 'function_call_output' || p.type === 'custom_tool_call_output') {
+      // 성공한 패치만 변경 파일에 넣는다.
+      const patch = st.patches[p.call_id];
+      if (patch) {
+        delete st.patches[p.call_id];
+        if (patchSucceeded(p.output)) for (const r of parsePatch(patch.text, st.cwd)) addChange(st.files, r, patch.at);
+      }
+      st.pending.delete(p.call_id);
+      st.lastKind = 'result';
+    }
+    if (what) {
+      st.lastTool = what;
+      if (p.call_id && p.type !== 'web_search_call') st.pending.set(p.call_id, p.name);
+      pushEvent(st, x.timestamp, 'tool', what);
+      st.lastKind = 'tool';
+    }
+  }
+}
+
+export const _test = { newState, applyLine, phaseOf, snapshot };
+
+export function collectCodex({ showEnded, budget, filesOf = openFiles, startOf = processStart }) {
+  const procs = findProcesses(isCodex);
+  if (!procs.length && !showEnded) return [];
+
+  const files = recentFiles();
+  const read = (path) => {
+    let st = states.get(path);
+    if (!st) states.set(path, (st = newState(path)));
+    if (st.tail.read((x) => applyLine(st, x), budget)) markDirty(path, () => snapshot(st));
+  };
+  for (const f of files) read(f.path);
+
+  const liveByPath = new Map();
+  const claim = (path, pid) => {
+    if (!files.some((f) => f.path === path)) {
+      try {
+        files.push({ path, mtime: statSync(path).mtimeMs });
+      } catch {
+        return false;
+      }
+    }
+    read(path);
+    liveByPath.set(path, pid);
+    return true;
+  };
+
+  // 프로세스가 열어 둔 rollout 파일(Linux)이 가장 정확하므로 먼저 짝짓는다.
+  const rest = [];
+  for (const p of procs) {
+    const opened = filesOf(p.pid)?.find((f) => isRollout(f) && !liveByPath.has(f));
+    if (!opened || !claim(opened, p.pid)) rest.push(p);
+  }
+
+  // 남은 프로세스는 같은 폴더에서 돌고 있는 수만큼, 가장 최근에 바뀐 세션 파일을 '실행 중'으로 본다.
+  // 시작 시각을 아는 프로세스에는 시작한 뒤에 쓰인 파일만 준다. 새 codex 에 방금 끝난 세션이 붙지 않게 한다.
+  const slots = new Map();
+  for (const p of rest) slots.set(p.cwd, [...(slots.get(p.cwd) ?? []), p.pid]);
+  for (const f of files) {
+    if (liveByPath.has(f.path)) continue;
+    const free = slots.get(states.get(f.path).cwd);
+    const i = free?.findIndex((pid) => {
+      const since = startOf(pid);
+      return since === null || f.mtime >= since;
+    }) ?? -1;
+    if (i >= 0) liveByPath.set(f.path, free.splice(i, 1)[0]);
+  }
+
+  const alive = new Set(procs.map((p) => p.pid));
+  for (const pid of foundByPid.keys()) if (!alive.has(pid)) foundByPid.delete(pid);
+  for (const [cwd, pids] of slots) {
+    for (const pid of [...pids]) {
+      const path = searchByCwd(pid, cwd, liveByPath, startOf);
+      if (path && claim(path, pid)) pids.splice(pids.indexOf(pid), 1);
+    }
+  }
+
+  const seen = new Set(files.map((f) => f.path));
+  for (const path of states.keys()) if (!seen.has(path)) states.delete(path);
+
+  const out = [];
+  for (const f of files) {
+    const st = states.get(f.path);
+    const pid = liveByPath.get(f.path);
+    const live = pid !== undefined;
+    if (!live && !showEnded) continue;
+    // 가격표에 없는 모델은 비용을 ? 로 보인다.
+    const cost = codexCost(st.model, st.tokens);
+    const used = st.tokens.total > 0;
+    out.push({
+      tool: 'codex',
+      id: st.id,
+      pid: pid ?? null,
+      kind: 'interactive',
+      name: basename(st.cwd ?? '') || 'codex',
+      cwd: st.cwd,
+      project: basename(st.cwd ?? ''),
+      branch: st.branch,
+      model: st.model,
+      live,
+      status: !live ? 'ended' : st.busy ? 'busy' : 'idle',
+      phase: phaseOf(st, live),
+      cost: cost?.total ?? (used ? 0 : null),
+      costNoCache: cost?.noCache ?? null,
+      costUnknown: used && !cost,
+      waitingFor: null,
+      now: st.lastTool ?? st.events.at(-1)?.text ?? '',
+      startedAt: st.startedAt,
+      updatedAt: f.mtime,
+      tokens: { ...st.tokens, sub: 0 },
+      context: { used: st.context, window: st.window || 258_400 },
+      events: st.events,
+      files: mergeFiles([{ agent: '메인', files: st.files }]),
+      turns: st.turns,
+      activity: st.activity,
+      members: [],
+    });
+  }
+
+  // 아직 세션 파일을 만들지 않은(첫 입력 전) codex 프로세스도 보여 준다.
+  for (const [cwd, pids] of slots) {
+    for (const pid of pids) {
+      out.push({ tool: 'codex', id: `pid-${pid}`, pid, kind: 'interactive', name: basename(cwd ?? '') || 'codex', cwd, project: basename(cwd ?? ''), live: true, status: 'idle', phase: { kind: 'idle', text: '첫 입력 대기' }, cost: null, now: '', updatedAt: Date.now(), tokens: emptyTokens(), context: { used: 0, window: 0 }, events: [], members: [] });
+    }
+  }
+  return out;
+}

package/src/sources/common.mjs

@@ -0,0 +1,228 @@
+import { basename } from 'node:path';
+import { mask, maskStrict, oneLine, plainText, stripControl, STRICT_NAME } from '../text.mjs';
+
+export const MAX_EVENTS = 40;
+// 끝난 서브에이전트(팀원)는 이 시간 동안 "완료"로 보였다가 목록에서 사라진다.
+export const MEMBER_FADE_MS = 6000;
+
+export function emptyTokens() {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+}
+
+const two = (n) => String(n).padStart(2, '0');
+// 사용자가 보는 날짜(로컬 시간대) 기준 날짜 키.
+export function dayKey(ms) {
+  const d = new Date(ms);
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+}
+
+// 오늘부터 거꾸로 n 일의 날짜 키.
+export function lastDays(n, now = Date.now()) {
+  const keys = [];
+  const d = new Date(now);
+  for (let i = 0; i < n; i++) {
+    keys.push(dayKey(d.getTime()));
+    d.setDate(d.getDate() - 1);
+  }
+  return keys;
+}
+
+// 지출 속도용 짧은 구간 장부. 비용을 5분 칸(키 = 칸 시작 시각 ms)에 모으고, 그 장부에서 가장 새 칸부터
+// 2시간 안의 칸만 남긴다. 기준이 시계가 아니라 기록 안의 시각이라 처음 읽기 중에도 칸 수가 일정하다.
+export const SLOT_MS = 5 * 60_000;
+const SLOT_KEEP_MS = 2 * 3600_000;
+
+export function addSlot(slots, at, cost, costNoCache, unknown) {
+  if (!Number.isFinite(at)) return;
+  const k = Math.floor(at / SLOT_MS) * SLOT_MS;
+  let s = slots[k];
+  if (!s) {
+    s = slots[k] = { cost: 0, costNoCache: 0, unknown: false };
+    const newest = Math.max(...Object.keys(slots).map(Number));
+    for (const key of Object.keys(slots)) if (Number(key) < newest - SLOT_KEEP_MS) delete slots[key];
+    if (!slots[k]) return;
+  }
+  s.cost += cost;
+  s.costNoCache += costNoCache;
+  if (unknown) s.unknown = true;
+}
+
+// 최근 1시간 합계. 시작 시각이 now 로부터 60분 안인 칸만 센다 (5분 단위 근사라 55~60분 구간).
+export const lastHourOf = (books, now = Date.now()) => slotsSince(books, now - 3600_000);
+
+// 시작 시각이 from 이후인 칸의 합계.
+function slotsSince(books, from) {
+  const out = { cost: 0, costNoCache: 0, unknown: false };
+  for (const slots of books)
+    for (const [k, s] of Object.entries(slots ?? {})) {
+      if (Number(k) < from) continue;
+      out.cost += s.cost;
+      out.costNoCache += s.costNoCache;
+      out.unknown ||= s.unknown;
+    }
+  return out;
+}
+
+// 하루 예산의 예상 속도용: 최근 1시간 중 로컬 자정 이후의 몫만 센다.
+// ms 는 실제로 센 칸이 덮는 길이다: 구간 시작을 칸 경계로 올린 시각부터 지금까지 (55~60분, 자정 직후면 더 짧다).
+export function recentTodayOf(books, now = Date.now()) {
+  const d = new Date(now);
+  const from = Math.max(now - 3600_000, new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime());
+  const start = Math.ceil(from / SLOT_MS) * SLOT_MS;
+  return { ...slotsSince(books, start), ms: Math.max(0, now - start) };
+}
+
+// 세션별 활동 장부: 토큰을 1시간 칸(키 = 칸 시작 시각 ms)에 모은다. 상세 패널의 24시간 막대가 쓴다.
+// 기준은 장부 안 가장 새 칸이라 처음 읽기 중에도 칸 수가 ACT_HOURS 를 넘지 않는다 (세션 하나에 숫자 24개).
+export const ACT_MS = 3600_000;
+export const ACT_HOURS = 24;
+// 시계가 어긋난 줄 하나가 미래 칸을 만들어 앞 칸을 모두 지우지 않게, 지금보다 이만큼 넘게 앞선 시각은 버린다.
+export const ACT_SKEW_MS = 5 * 60_000;
+
+export function addActivity(act, at, tokens, now = Date.now()) {
+  if (!Number.isFinite(at) || !(tokens > 0) || at > now + ACT_SKEW_MS) return;
+  const k = Math.floor(at / ACT_MS) * ACT_MS;
+  if (act[k] == null) {
+    const newest = Math.max(k, ...Object.keys(act).map(Number));
+    if (k <= newest - ACT_HOURS * ACT_MS) return;
+    for (const key of Object.keys(act)) if (Number(key) <= newest - ACT_HOURS * ACT_MS) delete act[key];
+    act[k] = 0;
+  }
+  act[k] += tokens;
+}
+
+// 여러 장부(메인 + 서브에이전트)를 칸별로 더한다.
+export function mergeActivity(books) {
+  const out = {};
+  for (const b of books) for (const [k, v] of Object.entries(b ?? {})) out[k] = (out[k] ?? 0) + v;
+  return out;
+}
+
+// now 가 든 칸까지 거꾸로 n 칸의 토큰 (오래된 칸 → 지금 칸).
+export function activitySeries(act, now = Date.now(), n = ACT_HOURS) {
+  const last = Math.floor(now / ACT_MS) * ACT_MS;
+  return Array.from({ length: n }, (_, i) => act?.[last - (n - 1 - i) * ACT_MS] ?? 0);
+}
+
+// 기록 줄의 timestamp. 없거나 읽을 수 없으면 지금 시각.
+export const parseTs = (ts) => (ts && Date.parse(ts)) || Date.now();
+
+// 답변(reply)은 마크다운 기호를 지운 평문으로 남긴다.
+export function pushEvent(state, at, kind, text) {
+  const t = mask(oneLine(kind === 'reply' ? plainText(text) : text));
+  if (!t) return null;
+  const e = { at: parseTs(at), kind, text: t };
+  state.events.push(e);
+  if (state.events.length > MAX_EVENTS) state.events.shift();
+  return e;
+}
+
+const short = (p) => (p ? basename(String(p)) : '');
+
+// 도구 호출을 "무엇을 하는지" 한 줄로 줄인다. Claude·Codex 도구 이름을 모두 다룬다.
+// 도구 설명은 화면·--json 어디로 나가든 비밀값을 가린 뒤 한 줄로 만든다.
+export function describeTool(name, input = {}) {
+  return mask(oneLine(rawDescribeTool(name, input)));
+}
+
+function rawDescribeTool(name, input) {
+  if (typeof input === 'string') {
+    const file = input.match(/\*\*\* (?:Update|Add|Delete) File: (.+)/);
+    return file ? `${name} ${short(file[1])}` : name;
+  }
+  switch (name) {
+    case 'Bash':
+    case 'exec_command':
+    case 'shell':
+      return `$ ${input.description ?? input.cmd ?? input.command ?? ''}`;
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+    case 'NotebookEdit':
+      return `${name} ${short(input.file_path ?? input.notebook_path)}`;
+    case 'Grep':
+    case 'Glob':
+      return `${name} ${input.pattern ?? ''}`;
+    case 'WebFetch':
+      return `WebFetch ${(input.url ?? '').replace(/^https?:\/\//, '').split('/')[0]}`;
+    case 'WebSearch':
+      return `WebSearch ${input.query ?? ''}`;
+    case 'Agent':
+    case 'Task':
+      return `▸ ${input.subagent_type ?? 'agent'}: ${input.description ?? ''}`;
+    case 'TodoWrite':
+      return 'TodoWrite';
+    default: {
+      const first = Object.values(input).find((v) => typeof v === 'string');
+      return first ? `${name} ${first}` : name;
+    }
+  }
+}
+
+// 허락을 기다리는 도구 호출의 전체 내용. 한 줄 설명(describeTool)과 달리 Bash 는 설명 대신 실제 명령을, 파일 도구는 전체 경로를 남긴다.
+// 화면 색을 바꾸는 ANSI 순서와 제어문자를 지우고 비밀값을 가린 뒤 DETAIL_MAX 자에서 자른다. 줄바꿈은 남긴다.
+export const DETAIL_MAX = 2048;
+const ANSI = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_])/g;
+
+export function toolDetail(name, input = {}) {
+  const raw = rawToolDetail(name, input);
+  if (!raw) return null;
+  const clean = maskStrict(stripControl(String(raw).replace(ANSI, '').replace(/\r\n?/g, '\n').replace(/\t/g, '  '))).trim();
+  if (!clean) return null;
+  return clean.length > DETAIL_MAX ? clean.slice(0, DETAIL_MAX - 1) + '…' : clean;
+}
+
+// 이름이 비밀값처럼 보이는 키(api_key, token, password, cookie 등)의 값은 문자열·숫자·객체·배열 가리지 않고 통째로 가린다.
+// { name: 'API_KEY', value: '…' } 처럼 이름과 값을 나눠 담은 항목도 value 를 가린다. 너무 깊은 곳은 통째로 가린다.
+const MAX_DEPTH = 32;
+const secretLabel = (x) => typeof x === 'string' && STRICT_NAME.test(x.replace(/^-{1,2}/, '').replace(/[:=]$/, ''));
+
+export function maskKeys(v, depth = 0) {
+  if (!v || typeof v !== 'object') return v;
+  if (depth > MAX_DEPTH) return '••••';
+  // ["--token", "x"], ["Authorization", "x"]: 비밀 이름 바로 다음 칸을 가린다.
+  if (Array.isArray(v)) {
+    let after = false;
+    return v.map((x) => {
+      const hide = after && x != null && typeof x !== 'boolean';
+      after = !hide && secretLabel(x);
+      return hide ? '••••' : maskKeys(x, depth + 1);
+    });
+  }
+  const label = v.name ?? v.Name ?? v.key ?? v.Key;
+  const pair = typeof label === 'string' && STRICT_NAME.test(label);
+  return Object.fromEntries(
+    Object.entries(v).map(([k, x]) => {
+      const secret = STRICT_NAME.test(k) || (pair && /^value$/i.test(k));
+      return [k, secret && x != null && typeof x !== 'boolean' ? '••••' : maskKeys(x, depth + 1)];
+    }),
+  );
+}
+
+function rawToolDetail(name, input) {
+  if (typeof input === 'string') return input;
+  if (!input || typeof input !== 'object') return null;
+  switch (name) {
+    case 'Bash':
+    case 'exec_command':
+    case 'shell': {
+      const cmd = input.command ?? input.cmd;
+      return Array.isArray(cmd) ? cmd.join(' ') : cmd;
+    }
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+    case 'NotebookEdit':
+      return input.file_path ?? input.notebook_path;
+    default:
+      try {
+        return Object.keys(input).length ? JSON.stringify(maskKeys(input)) : null;
+      } catch {
+        return null;
+      }
+  }
+}
+
+export function isNoisePrompt(text) {
+  return /^\s*(<|\[Request interrupted|Caveat:|This session is being continued from a previous conversation)/.test(text);
+}