elanous 0.2.36 → 0.2.38

package/src/tui/input/at-picker.ts

@@ -0,0 +1,55 @@
+import { readdir } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+
+/** Candidate contract matches the classic chat `onAtCandidates` shape. */
+export interface AtFileCandidate {
+  readonly label: string;
+  readonly absPath: string;
+  readonly isDir: false;
+}
+
+export interface AtQuery {
+  readonly prefix: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+export function parseAtQuery(text: string, cursor: number): AtQuery | null {
+  const head = text.slice(0, cursor);
+  const match = head.match(/(?:^|\s)@([\p{L}\p{N}_./~\\-]*)$/u);
+  if (!match) return null;
+  const prefix = match[1] ?? '';
+  return { prefix, start: head.length - prefix.length - 1, end: cursor };
+}
+
+/** List local files under root only; directories are traversal prefixes, never candidates. */
+export async function listAtFiles(prefix: string, root: string): Promise<AtFileCandidate[]> {
+  const slash = Math.max(prefix.lastIndexOf('/'), prefix.lastIndexOf('\\'));
+  const typedDir = slash < 0 ? '' : prefix.slice(0, slash + 1);
+  const partial = slash < 0 ? prefix : prefix.slice(slash + 1);
+  const dirPart = typedDir.replaceAll('\\', sep).replace(/^~(?=\/)/, '');
+  const base = resolve(root, dirPart || '.');
+  const inside = relative(resolve(root), base);
+  if (inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside)) return [];
+  try {
+    const entries = await readdir(base, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.toLocaleLowerCase().startsWith(partial.toLocaleLowerCase()))
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .slice(0, 15)
+      .map((entry) => ({ label: `${typedDir}${entry.name}`, absPath: resolve(base, entry.name), isDir: false as const }));
+  } catch {
+    return [];
+  }
+}
+
+export function acceptAtFile(text: string, query: AtQuery, candidate: AtFileCandidate, ordinal: number): { text: string; cursor: number; token: string } {
+  const token = `[attached ${ordinal}: ${basename(candidate.absPath)}]`;
+  const insertion = `${token} `;
+  const next = text.slice(0, query.start) + insertion + text.slice(query.end);
+  return { text: next, cursor: query.start + insertion.length, token };
+}
+
+export function attachmentsForMessage(text: string, selected: ReadonlyMap<string, string>): string[] {
+  return [...selected].filter(([token]) => text.includes(token)).map(([, path]) => path);
+}

package/src/tui/sidetab/attach.ts

@@ -0,0 +1,304 @@
+import { randomUUID } from 'node:crypto';
+import { resolveBackendSpawn, claudeBackend, codexBackend } from '../../agent-mission/driver.js';
+import { DisplayCoordinator } from '../../display/coordinator.js';
+import { createDisplayEventBus } from '../../display/events.js';
+import { createTerminalModalRouter } from '../../terminal/terminal-modal-router.js';
+import { getSessionCwd } from '../../session/working-dir.js';
+import { TerminalSessionRegistry, type TerminalSession } from '../../terminal/session-registry.js';
+import { requestRemotePtyControl } from '../../pty-shell/pty-control-ipc.js';
+import type { Key } from '../../tui.js';
+import type { SidetabRow } from './list.js';
+
+export type SidetabCharacter = 'shell' | 'elanous' | 'codex' | 'claude';
+
+export interface SidetabAttachmentController {
+  attach(row: SidetabRow): boolean;
+  select(row: SidetabRow): boolean;
+  showMain(): void;
+  spawn(character: SidetabCharacter): boolean;
+  kill(row: SidetabRow): boolean;
+  handleKey(key: Key): boolean;
+  hasModal(): boolean;
+  hasRemoteView(): boolean;
+  refresh(): void;
+  close(): void;
+}
+
+export function createSidetabAttachmentController(deps: {
+  drawBase(): void;
+  termSize(): { cols: number; rows: number };
+  setStatus(message: string): void;
+  drawRemoteFrame(frame: string): void;
+}): SidetabAttachmentController {
+  const eventBus = createDisplayEventBus();
+  const coordinator = new DisplayCoordinator({
+    termSize: deps.termSize,
+    onRender: () => deps.drawBase(),
+    writeOverlay: (ansi) => { try { process.stdout.write(ansi); } catch { /* TUI closed */ } },
+  });
+  const registry = new TerminalSessionRegistry({ coordinator, eventBus });
+  const modalRouter = createTerminalModalRouter();
+  let attachedSessionId: string | null = null;
+  let detachPrefixPending = false;
+  let remotePtyId: string | null = null;
+  let remoteTakenOver = false;
+  let remoteFrameTimer: ReturnType<typeof setInterval> | null = null;
+  let remoteFramePending = false;
+  let remoteHasFrame = false;
+
+  const stopRemote = (): void => {
+    if (remoteFrameTimer !== null) clearInterval(remoteFrameTimer);
+    remoteFrameTimer = null;
+    const previous = remotePtyId;
+    remotePtyId = null;
+    if (previous && remoteTakenOver) void requestRemotePtyControl(previous, 'release', undefined, { timeoutMs: 500 }).catch(() => {});
+    remoteTakenOver = false;
+    remoteHasFrame = false;
+    deps.drawRemoteFrame('');
+  };
+
+  const startRemote = (row: SidetabRow): boolean => {
+    if (!row.ptyId) return false;
+    stopRemote();
+    remotePtyId = row.ptyId;
+    const id = row.ptyId;
+    const refresh = async (): Promise<void> => {
+      if (remoteFramePending || remotePtyId !== id) return;
+      remoteFramePending = true;
+      try {
+        const result = await requestRemotePtyControl(id, 'snapshot', { ansi: true }, { timeoutMs: 450 });
+        if (remotePtyId === id && result.status === 'success') {
+          if (!result.screen?.trim()) {
+            stopRemote();
+            deps.setStatus('PTY 화면이 비어 있어 채팅 화면을 유지합니다');
+            return;
+          }
+          remoteHasFrame = true;
+          deps.drawRemoteFrame(result.screen ?? '');
+        }
+        else if (remotePtyId === id && result.status !== 'success') {
+          if (!remoteHasFrame) stopRemote();
+          deps.setStatus(`PTY 화면 읽기 실패 · ${result.status}`);
+        }
+      } catch (error) {
+        if (remotePtyId === id) {
+          if (!remoteHasFrame) stopRemote();
+          deps.setStatus(`PTY 화면 읽기 오류 · ${error instanceof Error ? error.message : String(error)}`);
+        }
+      } finally {
+        remoteFramePending = false;
+      }
+    };
+    void refresh();
+    remoteFrameTimer = setInterval(() => { void refresh(); }, 75);
+    deps.setStatus('원격 PTY 화면 · t takeover · Ctrl+\\ 후 ↑/↓ 전환');
+    return true;
+  };
+
+  const sessionForRow = (row: SidetabRow): TerminalSession | undefined =>
+    row.sessionId ? registry.get(row.sessionId) : undefined;
+
+  const setModal = (session: TerminalSession): boolean => {
+    if (!session.modal) return false;
+    attachedSessionId = session.id;
+    modalRouter.set(session.modal, {
+      onClose: () => {
+        registry.detach(session.id);
+        attachedSessionId = null;
+        deps.setStatus('PTY 분리됨 · 사이드탭에서 다시 선택 가능');
+        deps.drawBase();
+      },
+    });
+    deps.setStatus('PTY 입력 중 · Ctrl+\\ d 분리 · Ctrl+Q는 PTY에 전달');
+    coordinator.requestRenderNow({ force: true });
+    return true;
+  };
+
+  const spawn = (character: SidetabCharacter): boolean => {
+    const { cols, rows } = deps.termSize();
+    if (cols < 40 || rows < 8) {
+      deps.setStatus('PTY 모달은 최소 40칸 × 8줄이 필요합니다');
+      return false;
+    }
+    const id = `next-sidetab-${randomUUID()}`;
+    const cwd = getSessionCwd();
+    const title = character === 'claude' ? 'claude-code' : character;
+    const common = {
+      id,
+      title,
+      cwd,
+      useRegistry: true,
+      registryKind: character === 'claude' ? 'claude' : character,
+      registryNickname: `${character} · Next TUI`,
+      registryOrigin: { originRoot: 'elanous-internal', controller: 'next-tui-sidetab' },
+      registryPurpose: `next-tui-sidetab:${id}`,
+      registrySeat: process.env.COORD_ID?.trim() || 'unknown',
+      kind: character === 'shell' ? 'shell' as const : 'coding-agent' as const,
+      ...(character === 'claude' ? { agentBrand: 'claude-code' as const } : character === 'codex' ? { agentBrand: 'codex' as const } : {}),
+    };
+    try {
+      let command: string | undefined;
+      let env: Record<string, string> | undefined;
+      let unsetEnv: string[] | undefined;
+      if (character === 'elanous') command = 'elanous --tui next';
+      if (character === 'codex' || character === 'claude') {
+        const backend = character === 'codex' ? codexBackend : claudeBackend;
+        const spec = resolveBackendSpawn(backend, process.env);
+        command = [spec.cmd, ...spec.args].map(shellQuote).join(' ');
+        env = spec.env;
+        // buildPtyEnv applies the driver's explicit auth scrub list after
+        // merging captured login-shell variables; keep PATH/HOME/TERM intact.
+        unsetEnv = [...spec.unsetEnv];
+      }
+      const session = registry.spawn({
+        ...common,
+        ...(command ? { command } : {}),
+        ...(env ? { env } : {}),
+        ...(unsetEnv ? { unsetEnv } : {}),
+        onExit: () => {
+          if (attachedSessionId === id) {
+            modalRouter.set(null);
+            attachedSessionId = null;
+            deps.setStatus(`${title} 종료됨 · 사이드탭으로 돌아옴`);
+            deps.drawBase();
+          }
+        },
+      }, { termCols: cols, termRows: rows });
+      if (character === 'codex' || character === 'claude') {
+        deps.setStatus(`${character} 실행 · agent-mission 구독 경로 scrub 적용(${unsetEnv?.length ?? 0}개 env 제거)`);
+      }
+      return setModal(session);
+    } catch (error) {
+      deps.setStatus(`${character} 실행 실패: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  };
+
+  return {
+    attach(row) {
+      stopRemote();
+      if (row.currentProcess) {
+        showMain();
+        return true;
+      }
+      const session = sessionForRow(row);
+      if (!session) {
+        deps.setStatus('이 항목은 Next TUI에서 만든 세션이 아닙니다 · shell/agent 세션만 attach할 수 있습니다');
+        return false;
+      }
+      if (session.state === 'exited') {
+        deps.setStatus('종료된 PTY는 attach할 수 없습니다');
+        return false;
+      }
+      const { cols, rows } = deps.termSize();
+      const attached = registry.attach(session.id, { termCols: cols, termRows: rows });
+      return attached ? setModal(attached) : false;
+    },
+    select(row) {
+      if (row.ptyId && !row.currentProcess && !sessionForRow(row)) return startRemote(row);
+      if (row.currentProcess) {
+        showMain();
+        return true;
+      }
+      return this.attach(row);
+    },
+    showMain,
+    spawn,
+    kill(row) {
+      if (row.currentProcess) {
+        deps.setStatus('현재 TUI 세션은 사이드탭에서 종료할 수 없습니다');
+        return false;
+      }
+      const session = sessionForRow(row);
+      if (!session) {
+        if (row.ptyId) {
+          void requestRemotePtyControl(row.ptyId, 'terminate', undefined, { timeoutMs: 1_000 }).then((result) => {
+            deps.setStatus(result.status === 'success' ? 'PTY 종료 요청 완료' : `PTY 종료 거부 · ${result.status}`);
+          }).catch((error: unknown) => deps.setStatus(`PTY 종료 오류 · ${error instanceof Error ? error.message : String(error)}`));
+          return true;
+        }
+        deps.setStatus('이 항목은 이 Next TUI에서 종료할 수 없습니다');
+        return false;
+      }
+      if (attachedSessionId === session.id) {
+        modalRouter.set(null);
+        attachedSessionId = null;
+      }
+      registry.kill(session.id);
+      deps.setStatus(`${session.title} 종료 요청 완료`);
+      return true;
+    },
+    handleKey(key) {
+      if (remotePtyId) {
+        // Keep global TUI controls reachable while a remote snapshot is displayed.
+        if (key.ctrl && key.name.toLowerCase() === 'q') return false;
+        if (key.name.toLowerCase() === 't' && !remoteTakenOver) {
+          const id = remotePtyId;
+          void requestRemotePtyControl(id, 'takeover', undefined, { timeoutMs: 1_000 }).then((result) => {
+            if (remotePtyId !== id) return;
+            remoteTakenOver = result.status === 'success';
+            deps.setStatus(remoteTakenOver ? '사람 입력 takeover 완료 · 전환 때 release' : `takeover 거부 · ${result.reason ?? result.status}`);
+          }).catch((error: unknown) => {
+            if (remotePtyId === id) deps.setStatus(`takeover 오류 · ${error instanceof Error ? error.message : String(error)}`);
+          });
+          return true;
+        }
+        if (remoteTakenOver && key.raw) {
+          const id = remotePtyId;
+          void requestRemotePtyControl(id, 'input-key', { chars: key.raw }, { timeoutMs: 500 }).then((result) => {
+            if (remotePtyId === id && result.status !== 'success') deps.setStatus(`PTY 입력 실패 · ${result.status}`);
+          }).catch((error: unknown) => {
+            if (remotePtyId === id) deps.setStatus(`PTY 입력 오류 · ${error instanceof Error ? error.message : String(error)}`);
+          });
+          return true;
+        }
+        return true;
+      }
+      if (!modalRouter.current()) return false;
+      if (detachPrefixPending) {
+        detachPrefixPending = false;
+        if (key.name.toLowerCase() === 'd') {
+          modalRouter.close();
+          coordinator.requestRenderNow({ force: true });
+          return true;
+        }
+        deps.setStatus('분리 취소 · Ctrl+\\ d 를 눌러 분리');
+        coordinator.requestRenderNow({ force: true });
+        return true;
+      }
+      if (key.ctrl && key.name === '\\') {
+        detachPrefixPending = true;
+        deps.setStatus('분리 키 대기 · d');
+        return true;
+      }
+      const routed = modalRouter.handleKey({
+        name: key.name,
+        sequence: key.raw,
+        ctrl: key.ctrl,
+        shift: key.shift,
+        alt: key.alt,
+      });
+      if (routed !== 'passthrough') coordinator.requestRenderNow({ force: true });
+      return routed !== 'passthrough';
+    },
+    hasModal: () => modalRouter.current() !== null,
+    hasRemoteView: () => remotePtyId !== null,
+    refresh: () => coordinator.requestRenderNow({ force: true }),
+    close() {
+      stopRemote();
+      modalRouter.close();
+      for (const session of registry.list()) registry.kill(session.id);
+    },
+  };
+
+  function showMain(): void {
+    stopRemote();
+    if (attachedSessionId === null) return;
+    modalRouter.close();
+    coordinator.requestRenderNow({ force: true });
+  }
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/tui/sidetab/list.ts

@@ -0,0 +1,176 @@
+import { resolveInstanceName } from '../../instance-identity.js';
+import { listPtyManifestRows, type PtyManifestRow } from '../../pty-shell/pty-manifest.js';
+import { describePtyRunState } from '../../pty-shell/tui-run-state.js';
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+export type SidetabBadge = 'busy' | 'idle' | 'stale' | 'unknown' | 'exited';
+
+export interface SidetabRow {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: string;
+  readonly badge: SidetabBadge;
+  readonly sessionId?: string;
+  readonly ptyId?: string;
+  readonly nestDepth?: number;
+  readonly ownerPid?: number;
+  readonly currentProcess?: boolean;
+}
+
+export interface SidetabState {
+  readonly open: boolean;
+  readonly selected: number;
+}
+
+export interface SidetabScope {
+  readonly all?: boolean;
+  readonly currentPtyId?: string;
+  readonly currentPid?: number;
+  /** Current classic chat session; classic shell rows carry it in their purpose tag. */
+  readonly currentSessionId?: string;
+}
+
+export type SidetabKey = 'toggle' | 'up' | 'down' | 'other';
+
+export function createSidetabState(): SidetabState {
+  return { open: false, selected: 0 };
+}
+
+export function sidetabWidthForTerminal(columns: number): number {
+  return columns < 34 ? 0 : Math.min(28, Math.max(12, Math.floor(columns / 3)));
+}
+
+export function sidetabRowIndexAtTerminalRow(rowCount: number, selected: number, panelHeight: number, terminalRow: number): number | null {
+  const rowCapacity = Math.max(0, Math.floor(panelHeight) - 3);
+  const visibleCount = Math.min(rowCount, rowCapacity);
+  const offset = terminalRow - 3;
+  if (visibleCount === 0 || offset < 0 || offset >= visibleCount) return null;
+  const start = rowCount <= visibleCount
+    ? 0
+    : Math.max(0, Math.min(selected - visibleCount + 1, rowCount - visibleCount));
+  return start + offset;
+}
+
+export function applySidetabKey(state: SidetabState, key: SidetabKey, rowCount: number): SidetabState {
+  if (key === 'toggle') return { ...state, open: !state.open, selected: Math.min(state.selected, Math.max(0, rowCount - 1)) };
+  if (!state.open || rowCount === 0 || (key !== 'up' && key !== 'down')) return state;
+  const delta = key === 'up' ? -1 : 1;
+  return { ...state, selected: (state.selected + delta + rowCount) % rowCount };
+}
+
+export function sidetabRowsFromManifest(
+  rows: readonly PtyManifestRow[],
+  instance: string,
+  runState: (row: PtyManifestRow) => { turn: string; stale: boolean | null } = describePtyRunState,
+  scope?: SidetabScope,
+): SidetabRow[] {
+  const currentPid = scope?.currentPid ?? process.pid;
+  const currentSessionId = scope?.currentSessionId;
+  const eligible = rows.filter((row) => row.instance === instance && (
+    (row.kind === 'tui' && Boolean(row.sessionId))
+    || Boolean(row.parentPtyId)
+    || row.purpose?.startsWith('next-tui-sidetab:')
+    || (row.kind === 'shell'
+      && currentSessionId !== undefined
+      && row.parentPid === currentPid
+      && row.purpose?.includes(`:session:${currentSessionId}:terminal:`))
+  ));
+  let scoped = eligible;
+  if (scope) {
+    const parent = eligible.find((row) => row.kind === 'tui'
+      && (row.id === (scope.currentPtyId ?? `tui:${currentPid}`) || row.ownerPid === currentPid));
+    if (!scope.all) {
+      const includedIds = new Set<string>(parent ? [parent.id] : []);
+      const includedPids = new Set<number>(parent ? [parent.ownerPid, parent.ptyPid, currentPid] : [currentPid]);
+      let changed = true;
+      while (changed) {
+        changed = false;
+        for (const row of eligible) {
+          if (row.kind === 'tui' || includedIds.has(row.id)) continue;
+          if ((row.parentPtyId && includedIds.has(row.parentPtyId)) || (row.parentPid > 0 && includedPids.has(row.parentPid))) {
+            includedIds.add(row.id);
+            if (row.ownerPid > 0) includedPids.add(row.ownerPid);
+            if (row.ptyPid > 0) includedPids.add(row.ptyPid);
+            changed = true;
+          }
+        }
+      }
+      scoped = eligible.filter((row) => includedIds.has(row.id));
+    }
+    if (!scope.all) scoped = scoped.filter((row) => row.alive);
+  }
+  return scoped
+    .map((row) => {
+      const badge: SidetabBadge = !row.alive
+        ? 'exited'
+        : (() => {
+            const state = runState(row);
+            return state.stale === true ? 'stale' : state.turn === 'busy' ? 'busy' : state.turn === 'idle' ? 'idle' : 'unknown';
+          })();
+      const sessionId = row.purpose?.startsWith('next-tui-sidetab:') ? row.purpose.slice('next-tui-sidetab:'.length) : undefined;
+      const classicTerminalSessionId = currentSessionId !== undefined && row.kind === 'shell'
+        ? row.purpose?.split(`:session:${currentSessionId}:terminal:`)[1]
+        : undefined;
+      return {
+        id: row.id,
+        label: `${'  '.repeat(Math.min(2, row.nestDepth ?? 0))}${row.nickname || row.purpose || row.cmd || row.kind}`,
+        ...(row.sessionId ? { sessionId: row.sessionId } : {}),
+        kind: row.kind,
+        badge,
+        ptyId: row.id,
+        nestDepth: row.nestDepth,
+        ownerPid: row.ownerPid,
+        currentProcess: row.kind === 'tui' && row.ownerPid === process.pid,
+        ...(sessionId ? { sessionId } : classicTerminalSessionId ? { sessionId: classicTerminalSessionId } : {}),
+      };
+    });
+}
+
+export function loadSidetabRows(all = false, currentSessionId?: string): SidetabRow[] {
+  return sidetabRowsFromManifest(listPtyManifestRows(), resolveInstanceName(), describePtyRunState, {
+    all,
+    ...(currentSessionId ? { currentSessionId } : {}),
+  });
+}
+
+export function formatSidetabLines(
+  rows: readonly SidetabRow[],
+  selected: number,
+  width: number,
+  height = Number.POSITIVE_INFINITY,
+  mode: 'list' | 'new' = 'list',
+): string[] {
+  const fit = (value: string): string => {
+    const segments = [...graphemes.segment(value)].map(({ segment }) => segment);
+    const truncated = Bun.stringWidth(value) > width;
+    const limit = truncated ? Math.max(0, width - 1) : width;
+    let result = '';
+    let used = 0;
+    for (const segment of segments) {
+      const cells = Bun.stringWidth(segment);
+      if (used + cells > limit) break;
+      result += segment;
+      used += cells;
+    }
+    if (truncated && width > 0) { result += '…'; used++; }
+    return result + ' '.repeat(Math.max(0, width - used));
+  };
+  const lines = mode === 'new'
+    ? [fit(' 새 PTY'), fit(' s shell · e elanous'), fit(' c codex · l claude · Esc')]
+    : [fit(' 세션 · PTY'), fit(' ↑↓ 전환 · 클릭 선택')];
+  const rowCapacity = Math.max(0, Math.floor(height) - lines.length - (mode === 'list' ? 1 : 0));
+  const visibleCount = Math.min(rows.length || 1, rowCapacity);
+  const start = rows.length <= visibleCount
+    ? 0
+    : Math.max(0, Math.min(selected - visibleCount + 1, rows.length - visibleCount));
+  if (mode === 'list' && rows.length === 0 && visibleCount > 0) lines.push(fit(' 항목 없음'));
+  for (let offset = 0; offset < visibleCount && rows.length > 0; offset++) {
+    const index = start + offset;
+    const row = rows[index]!;
+    const marker = index === selected ? '›' : ' ';
+    lines.push(fit(` ${marker} ${row.badge} ${row.label}`));
+  }
+  if (mode === 'list' && lines.length < Math.floor(height)) lines.push(fit(' + new · /side new'));
+  return lines;
+}

package/src/tui/sidetab/nl-tool.ts

@@ -0,0 +1,136 @@
+import type { LLMToolSpec } from '../../llm.js';
+import type { SidetabRow } from './list.js';
+
+export const NEXT_SIDETAB_TOOL_NAME = 'NextSidetab';
+const CALL = 'elanous.sidetab.call';
+const RESULT = 'elanous.sidetab.result';
+
+export type NextSidetabAction = 'list' | 'switch' | 'attach' | 'detach' | 'new' | 'kill';
+export interface NextSidetabRequest {
+  action: NextSidetabAction;
+  target?: string;
+  character?: 'shell' | 'elanous';
+  confirm?: boolean;
+}
+export interface NextSidetabCall { type: typeof CALL; callId: string; request: NextSidetabRequest }
+export interface NextSidetabResult { type: typeof RESULT; callId: string; result: unknown }
+export type NextSidetabHandler = (request: NextSidetabRequest) => Promise<unknown>;
+export interface NextSidetabHostDeps {
+  rows(): readonly SidetabRow[] | Promise<readonly SidetabRow[]>;
+  selected(): number;
+  switchSession(row: SidetabRow): Promise<unknown>;
+  attach(row: SidetabRow): Promise<unknown>;
+  detach(): unknown;
+  spawn(character: 'shell' | 'elanous'): unknown;
+  kill(row: SidetabRow): unknown;
+}
+export interface NextSidetabIpcProcess {
+  send?: (message: unknown) => boolean | void;
+  on(event: 'message', listener: (message: unknown) => void): unknown;
+}
+
+export const nextSidetabToolSpec: LLMToolSpec = {
+  name: NEXT_SIDETAB_TOOL_NAME,
+  description: 'Control the Next TUI side tab: list/view sessions and PTYs, switch sessions, attach or detach, start a local shell or elanous PTY, or kill a PTY. Ask the user to confirm before calling kill with confirm=true. Starting coding agents is not supported.',
+  parameters: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['list', 'switch', 'attach', 'detach', 'new', 'kill'] },
+      target: { type: 'string', description: 'Optional exact or partial row id/label; required for targeted actions.' },
+      character: { type: 'string', enum: ['shell', 'elanous'], description: 'Only used with action=new.' },
+      confirm: { type: 'boolean', description: 'Must be true only after the user explicitly confirmed killing the selected PTY.' },
+    },
+    required: ['action'],
+    additionalProperties: false,
+  },
+};
+
+export function isNextSidetabCall(value: unknown): value is NextSidetabCall {
+  const call = value as Partial<NextSidetabCall> | null;
+  return Boolean(call && call.type === CALL && typeof call.callId === 'string'
+    && call.request && typeof call.request === 'object');
+}
+
+export async function answerNextSidetabCall(handler: NextSidetabHandler, call: NextSidetabCall): Promise<NextSidetabResult> {
+  try { return { type: RESULT, callId: call.callId, result: await handler(call.request) }; }
+  catch (error) {
+    return { type: RESULT, callId: call.callId, result: { error: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+export function createNextSidetabHostHandler(deps: NextSidetabHostDeps): NextSidetabHandler {
+  return async (request) => {
+    if (!request || !['list', 'switch', 'attach', 'detach', 'new', 'kill'].includes(request.action)) {
+      return { error: '지원하지 않는 사이드탭 동작입니다' };
+    }
+    if (request.action === 'new') {
+      if (request.character !== 'shell' && request.character !== 'elanous') return { error: 'character는 shell 또는 elanous여야 합니다' };
+      return deps.spawn(request.character);
+    }
+    if (request.action === 'detach') return deps.detach();
+    const rows = await deps.rows();
+    if (request.action === 'list') return rows.map(({ id, label, kind, badge, sessionId }) => ({ id, label, kind, badge, ...(sessionId ? { sessionId } : {}) }));
+    const target = request.target?.trim();
+    const exact = target ? rows.find((item) => item.id === target)
+      ?? rows.find((item) => item.label.toLowerCase() === target.toLowerCase()) : undefined;
+    const partial = target && !exact ? rows.filter((item) => item.label.toLowerCase().includes(target.toLowerCase())) : [];
+    if (partial.length > 1) return { error: `사이드탭 항목이 여러 개 일치합니다: ${target}` };
+    const row = exact ?? partial[0] ?? (target ? undefined : rows[deps.selected()]);
+    if (!row) return { error: target ? `사이드탭 항목을 찾지 못했습니다: ${target}` : '선택된 사이드탭 항목이 없습니다' };
+    if (request.action === 'switch') return row.kind === 'tui' ? deps.switchSession(row) : { error: 'Next TUI 세션만 전환할 수 있습니다' };
+    if (request.action === 'attach') return deps.attach(row);
+    if (row.currentProcess) return { error: '현재 TUI 세션은 사이드탭에서 종료할 수 없습니다' };
+    if (request.confirm !== true) return { needsConfirmation: true, message: `PTY 종료 확인 필요: ${row.label}` };
+    return deps.kill(row);
+  };
+}
+
+export function createReplNextSidetabTool(
+  proc: NextSidetabIpcProcess,
+  env: NodeJS.ProcessEnv = process.env,
+  timeoutMs = 15_000,
+): { spec: LLMToolSpec; dispatch: (args: Record<string, unknown>) => Promise<unknown> } | null {
+  if (env.ELANOUS_NEXT_TUI_SIDETAB_IPC !== '1' || typeof proc.send !== 'function') return null;
+  const send = proc.send.bind(proc);
+  const waiting = new Map<string, (result: unknown) => void>();
+  let sequence = 0;
+  const listener = (message: unknown): void => {
+    const result = message as Partial<NextSidetabResult> | null;
+    if (!result || result.type !== RESULT || typeof result.callId !== 'string') return;
+    const resolve = waiting.get(result.callId);
+    if (!resolve) return;
+    waiting.delete(result.callId);
+    resolve(result.result);
+  };
+  proc.on('message', listener);
+  return {
+    spec: nextSidetabToolSpec,
+    dispatch: (args) => new Promise((resolve) => {
+      const callId = `s${++sequence}`;
+      const timer = setTimeout(() => {
+        if (!waiting.delete(callId)) return;
+        resolve({ error: 'Next TUI did not answer the side-tab request' });
+      }, timeoutMs);
+      waiting.set(callId, (result) => { clearTimeout(timer); resolve(result); });
+      try {
+        send({ type: CALL, callId, request: args as unknown as NextSidetabRequest } satisfies NextSidetabCall);
+      } catch (error) {
+        waiting.delete(callId);
+        clearTimeout(timer);
+        resolve({ error: `Next TUI IPC send failed: ${error instanceof Error ? error.message : String(error)}` });
+      }
+    }),
+  };
+}
+
+export function registerNextSidetabReplTool(
+  specs: LLMToolSpec[],
+  dispatchByName: Map<string, (args: Record<string, unknown>) => Promise<unknown>>,
+  proc: NextSidetabIpcProcess,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const tool = createReplNextSidetabTool(proc, env);
+  if (!tool) return;
+  specs.push(tool.spec);
+  dispatchByName.set(tool.spec.name, tool.dispatch);
+}