elanous 0.2.34 → 0.2.36

package/src/tui-client/local-chat-turn.ts

@@ -0,0 +1,282 @@
+/** Keep one REPL child per session so background tasks and their completion queue survive turns. */
+import type { NextTuiCompactDeps, NextTuiCompactOutcome } from '../tui/slash/compact.js';
+import { NEXT_TUI_WAKEUP_IPC_ENV, answerWakeupCall, isWakeupCallMessage, nextTuiWakeupTool } from './next-wakeup.js';
+import { isNextTuiSelfHealthSnapshot, type NextTuiSelfHealthSnapshot } from '../tui/chat/self-health-status.js';
+
+const STATUS_PREFIX = 'ELANOUS_TUI_BG_STATUS\t';
+
+interface TurnResult {
+  event?: string | null;
+  turnId?: string | null;
+  sessionId?: string;
+  text?: string;
+  error?: string;
+  provider?: string;
+  model?: string | null;
+  selfHealth?: NextTuiSelfHealthSnapshot | null;
+}
+interface WaitingTurn {
+  turnId: string;
+  onDelta?: (text: string) => void;
+  resolve: (result: TurnResult) => void;
+  reject: (error: Error) => void;
+}
+
+class LocalChatSession {
+  readonly child: ReturnType<typeof Bun.spawn>;
+  readonly exited: Promise<number>;
+  private readonly writeInput: (payload: string) => Promise<void>;
+  private waiting: WaitingTurn | null = null;
+  private stderrTail = '';
+  private closed = false;
+  private closing: Promise<void> | null = null;
+  private invalidated = false;
+  private turnCount = 0;
+
+  constructor(private readonly sessionId: string, cli: string) {
+    // TUI-NEXT-QUEUE-AND-WAKE: the child's ScheduleWakeup asks this process over Bun IPC — the scheduler
+    // lives here because the child dies on Esc and /new. No tool registered → no IPC, env unchanged.
+    const wakeupTool = nextTuiWakeupTool();
+    this.child = Bun.spawn({
+      cmd: [process.execPath, cli, 'repl', '--session', sessionId, '--json', '--stdin-jsonl'],
+      stdin: 'pipe', stdout: 'pipe', stderr: 'pipe',
+      env: {
+        ...process.env, ELANOUS_NEXT_TUI_BG_STATUS: '1', ELANOUS_NEXT_TUI_STREAM: '1',
+        ELANOUS_NEXT_TUI_SELF_HEALTH: '1',
+        ...(wakeupTool ? { [NEXT_TUI_WAKEUP_IPC_ENV]: '1' } : {}),
+      },
+      ...(wakeupTool ? {
+        ipc: (message: unknown, child: { send(message: unknown): unknown }) => {
+          if (!isWakeupCallMessage(message)) return;
+          void answerWakeupCall(wakeupTool, message).then((reply) => {
+            try { child.send(reply); } catch { /* the child exited mid-call; its dispatch times out */ }
+          });
+        },
+      } : {}),
+    });
+    const input = this.child.stdin;
+    const output = this.child.stdout;
+    const errors = this.child.stderr;
+    if (!input || typeof input === 'number' || !output || typeof output === 'number'
+      || !errors || typeof errors === 'number') throw new Error('REPL pipe unavailable');
+    this.writeInput = async (payload) => { input.write(payload); await input.flush(); };
+    this.exited = this.child.exited;
+    void this.readLines(output, (line) => {
+      if (!line.trim()) return;
+      let result: TurnResult;
+      try { result = JSON.parse(line) as TurnResult; }
+      catch { this.fail(new Error(`invalid REPL JSONL response: ${line.slice(0, 160)}`)); return; }
+      if (result.event === 'self-health') {
+        const waiting = this.waiting;
+        if (!waiting || result.turnId !== waiting.turnId || result.sessionId !== this.sessionId
+          || !isNextTuiSelfHealthSnapshot(result.selfHealth) || result.selfHealth.sessionId !== this.sessionId) return;
+        const snapshot = Object.freeze(result.selfHealth);
+        for (const listener of selfHealthListeners.get(this.sessionId) ?? []) {
+          try { listener(snapshot); } catch { /* status observers cannot break the turn */ }
+        }
+        return;
+      }
+      const waiting = this.waiting;
+      if (!waiting) return;
+      if ('turnId' in result && result.turnId !== waiting.turnId) return;
+      if (result.event === 'delta') {
+        if (result.turnId !== waiting.turnId) return;
+        if (typeof result.text === 'string') {
+          try { waiting.onDelta?.(result.text); } catch { /* renderer cannot break the turn */ }
+        }
+        return;
+      }
+      // Future side-channel events cannot complete a turn. Legacy final
+      // frames have no event; typed final frames use event=result.
+      if ('event' in result && result.event !== 'result') return;
+      this.waiting = null;
+      waiting.resolve(result);
+    }, () => {
+      this.invalidate();
+      this.fail(new Error('REPL stdout closed'));
+      void this.close();
+    });
+    void this.readLines(errors, (line) => {
+      if (line.startsWith(STATUS_PREFIX)) {
+        for (const listener of statusListeners.get(sessionId) ?? []) {
+          try { listener(line.slice(STATUS_PREFIX.length)); } catch { /* status observers cannot break the turn */ }
+        }
+      } else if (line.trim()) {
+        this.stderrTail = line.trim();
+      }
+    });
+    void this.exited.then((code) => {
+      this.closed = true;
+      this.invalidate();
+      if (sessions.get(sessionId) === this) sessions.delete(sessionId);
+      this.fail(new Error(this.stderrTail || `chat exit ${code}`));
+    });
+  }
+
+  private async readLines(stream: ReadableStream<Uint8Array>, receive: (line: string) => void, onEnd?: () => void): Promise<void> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let newline: number;
+        while ((newline = buffer.indexOf('\n')) >= 0) {
+          receive(buffer.slice(0, newline));
+          buffer = buffer.slice(newline + 1);
+        }
+      }
+      buffer += decoder.decode();
+      if (buffer) receive(buffer);
+    } catch (error) {
+      this.fail(error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      reader.releaseLock();
+      onEnd?.();
+    }
+  }
+
+  private fail(error: Error): void {
+    const waiting = this.waiting;
+    this.waiting = null;
+    waiting?.reject(error);
+  }
+
+  private invalidate(): void {
+    if (this.invalidated) return;
+    this.invalidated = true;
+    for (const listener of statusListeners.get(this.sessionId) ?? []) {
+      try { listener(null); } catch { /* status observers cannot break teardown */ }
+    }
+    for (const listener of selfHealthListeners.get(this.sessionId) ?? []) {
+      try { listener(null); } catch { /* status observers cannot break teardown */ }
+    }
+  }
+
+  async turn(prompt: string, writePrompt?: (payload: string) => Promise<void>, onDelta?: (text: string) => void): Promise<TurnResult> {
+    if (this.closed) throw new Error('REPL child exited');
+    if (this.waiting) throw new Error('REPL turn already running');
+    const turnId = `tui-${++this.turnCount}`;
+    const payload = `${JSON.stringify({ prompt, id: turnId })}\n`;
+    const response = new Promise<TurnResult>((resolve, reject) => { this.waiting = { turnId, onDelta, resolve, reject }; });
+    try {
+      if (writePrompt) await writePrompt(payload);
+      else await this.writeInput(payload);
+    } catch (error) {
+      this.fail(error instanceof Error ? error : new Error(String(error)));
+    }
+    return response;
+  }
+
+  async close(): Promise<void> {
+    if (!this.closing) {
+      this.closing = (async () => {
+        if (!this.closed) {
+          this.closed = true;
+          this.invalidate();
+          try { this.child.kill(); } catch { /* already exited */ }
+        }
+        await this.exited;
+      })();
+    }
+    await this.closing;
+  }
+}
+
+const sessions = new Map<string, LocalChatSession>();
+/** Model the child last answered with, per session — sizes the next pre-turn compaction check. */
+const lastModels = new Map<string, string>();
+
+export function localChatModel(sessionId: string): string | null {
+  return lastModels.get(sessionId) ?? null;
+}
+
+/** TUI-NEXT-COMPACT — pre-turn auto compaction hook (deps are test seams; production passes none). */
+export interface LocalChatTurnCompact {
+  readonly deps?: NextTuiCompactDeps;
+  readonly onCompact?: (outcome: NextTuiCompactOutcome) => void;
+}
+const statusListeners = new Map<string, Set<(json: string | null) => void>>();
+const selfHealthListeners = new Map<string, Set<(snapshot: NextTuiSelfHealthSnapshot | null) => void>>();
+
+export function onLocalChatBackgroundStatus(sessionId: string, listener: (json: string | null) => void): () => void {
+  const listeners = statusListeners.get(sessionId) ?? new Set();
+  listeners.add(listener);
+  statusListeners.set(sessionId, listeners);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) statusListeners.delete(sessionId);
+  };
+}
+
+export function onLocalChatSelfHealthStatus(sessionId: string, listener: (snapshot: NextTuiSelfHealthSnapshot | null) => void): () => void {
+  const listeners = selfHealthListeners.get(sessionId) ?? new Set();
+  listeners.add(listener);
+  selfHealthListeners.set(sessionId, listeners);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) selfHealthListeners.delete(sessionId);
+  };
+}
+
+export async function closeLocalChatSession(sessionId: string): Promise<void> {
+  const session = sessions.get(sessionId);
+  sessions.delete(sessionId);
+  lastModels.delete(sessionId);
+  await session?.close();
+}
+
+/** Run one turn while retaining the child for the next turn. */
+export async function runLocalChatTurn(
+  sessionId: string,
+  text: string,
+  signal: AbortSignal,
+  cli = process.argv[1],
+  writePrompt?: (payload: string) => Promise<void>,
+  onDelta?: (text: string) => void,
+  compact: LocalChatTurnCompact = {},
+): Promise<void> {
+  if (signal.aborted) throw new Error('응답을 취소했습니다');
+  if (!cli) throw new Error('elanous CLI entry is unavailable');
+  // The REPL child reloads the session store each turn, so compacting the store here is what this
+  // turn's model call sees. Over the shared threshold only; a failure leaves the turn uncompacted.
+  // Lazy like this module itself: the compaction path pulls in the LLM router, so next TUI boot stays light.
+  const { compactNextTuiSession } = await import('../tui/slash/compact.js');
+  const compacted = await compactNextTuiSession(sessionId, { force: false, modelId: localChatModel(sessionId) }, compact.deps);
+  if (compacted.fired) {
+    try { compact.onCompact?.(compacted); } catch { /* status observers cannot break the turn */ }
+  }
+  if (signal.aborted) throw new Error('응답을 취소했습니다');
+  const session = sessions.get(sessionId) ?? new LocalChatSession(sessionId, cli);
+  sessions.set(sessionId, session);
+  const abort = (): void => { void closeLocalChatSession(sessionId); };
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) abort();
+  let result: TurnResult;
+  try {
+    result = await session.turn(text, writePrompt, (delta) => {
+      if (!signal.aborted) onDelta?.(delta);
+    });
+  } catch (error) {
+    if (signal.aborted) throw new Error('응답을 취소했습니다');
+    await closeLocalChatSession(sessionId);
+    throw error;
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+  if (signal.aborted) throw new Error('응답을 취소했습니다');
+  // A completed JSONL error frame is a turn failure, not a transport failure:
+  // the child still owns live tasks and buffered notifications for retry.
+  if (result.error) throw new Error(result.error);
+  if (result.model) lastModels.set(sessionId, result.model);
+  if (result.provider) {
+    try {
+      const { debug } = await import('../debug/log.js');
+      debug.log('llm.route-decision', 'local-chat-executed', {
+        surface: 'tui-local', sessionId, provider: result.provider, model: result.model ?? null,
+      });
+    } catch { /* observation must not fail a completed turn */ }
+  }
+}

package/src/tui-client/local-harness-command.ts

@@ -0,0 +1,63 @@
+/** Run the existing harness CLI outside the TUI import graph and stream its result. */
+export async function runLocalHarnessCommand(
+  command: 'ask' | 'runs',
+  goal: string,
+  signal: AbortSignal,
+  onLine: (line: string) => void,
+  cli = process.argv[1],
+): Promise<void> {
+  if (signal.aborted) throw new Error('하니스 호출을 취소했습니다');
+  if (!cli) throw new Error('elanous CLI entry is unavailable');
+  const dryRun = command === 'ask' && goal.startsWith('--dry-run ');
+  const objective = dryRun ? goal.slice('--dry-run '.length).trim() : goal;
+  if (command === 'ask' && !objective) throw new Error('하니스 목표가 비었습니다');
+  const cmd = command === 'runs'
+    ? [process.execPath, cli, 'harness', 'progress']
+    : [process.execPath, cli, 'harness', 'say', '--no-auto-merge', ...(dryRun ? ['--dry-run'] : []), objective];
+  const child = Bun.spawn({ cmd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe', env: process.env });
+  let omittedRunRows = 0;
+  let shownRunRows = 0;
+  const emit = (line: string): void => {
+    if (command === 'runs' && shownRunRows >= 16) { omittedRunRows++; return; }
+    shownRunRows++;
+    onLine(line);
+  };
+  const abort = (): void => { child.kill(); };
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) abort();
+  const readLines = async (stream: ReadableStream<Uint8Array>): Promise<string> => {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    let last = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      pending += decoder.decode(value, { stream: !done });
+      let newline = pending.indexOf('\n');
+      while (newline >= 0) {
+        const line = pending.slice(0, newline).replace(/\r$/, '');
+        if (line.trim()) { emit(line); last = line; }
+        pending = pending.slice(newline + 1);
+        newline = pending.indexOf('\n');
+      }
+      if (done) break;
+    }
+    if (pending.trim()) { emit(pending); last = pending; }
+    return last;
+  };
+  try {
+    const [outLast, errLast, code] = await Promise.all([
+      readLines(child.stdout), readLines(child.stderr), child.exited,
+    ]);
+    if (signal.aborted) throw new Error('하니스 호출을 취소했습니다');
+    if (code !== 0) throw new Error(errLast || outLast || `harness exit ${code}`);
+    if (omittedRunRows > 0) onLine(`추가 ${omittedRunRows}행 생략 · 전체: eln harness progress`);
+  } catch (error) {
+    try { child.kill(); } catch { /* already exited */ }
+    await child.exited;
+    if (signal.aborted) throw new Error('하니스 호출을 취소했습니다');
+    throw error;
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+}

package/src/tui-client/local-provider-command.ts

@@ -0,0 +1,184 @@
+import { loadCatalog } from '../intelligence-map/model-catalog.js';
+import { getUserConfig, PROVIDER_DEFAULT_MODEL, reloadUserConfig } from '../user-config.js';
+
+type FetchModels = (url: string, init: RequestInit) => Promise<Response>;
+type ModelList = { ids: string[]; source: 'remote' | 'cache' | 'local'; note?: string };
+
+const MODEL_LOOKUP_TIMEOUT_MS = 2_000;
+const MODEL_DISPLAY_LIMIT = 12;
+
+/** The provider command is imported only when opened; this cache lives for one TUI process. */
+export class ProviderModelCache {
+  private local = new Map<string, string[]>();
+  private lastGoodRemote = new Map<string, { apiKey: string | undefined; ids: string[] }>();
+
+  localModels(provider: string): string[] {
+    const cached = this.local.get(provider);
+    if (cached) return cached;
+    const ids = [...new Set(loadCatalog().catalog.models
+      .filter((model) => model.provider === provider)
+      .map((model) => model.id))].sort();
+    this.local.set(provider, ids);
+    return ids;
+  }
+
+  async models(
+    provider: string,
+    remoteUrl: string | undefined,
+    apiKey: string | undefined,
+    signal: AbortSignal,
+    refresh = false,
+    fetchModels: FetchModels = fetch,
+    timeoutMs = MODEL_LOOKUP_TIMEOUT_MS,
+  ): Promise<ModelList> {
+    if (signal.aborted) throw new Error('provider lookup cancelled');
+    const local = this.localModels(provider);
+    if (!remoteUrl) return { ids: local, source: 'local' };
+    const cacheKey = `${provider}\0${remoteUrl}`;
+    const cached = this.lastGoodRemote.get(cacheKey);
+    const previous = cached && cached.apiKey === apiKey ? cached.ids : undefined;
+    if (previous && !refresh) return { ids: previous, source: 'cache' };
+    try {
+      const ids = await queryRemoteModels(remoteUrl, apiKey, signal, fetchModels, timeoutMs);
+      this.lastGoodRemote.set(cacheKey, { apiKey, ids });
+      return { ids, source: 'remote' };
+    } catch (error) {
+      if (signal.aborted) throw error;
+      const note = error instanceof Error ? error.message : String(error);
+      if (previous) return { ids: previous, source: 'cache', note };
+      return { ids: local, source: 'local', note };
+    }
+  }
+}
+
+const cache = new ProviderModelCache();
+const supportedProvider = (name: string): boolean => Object.prototype.hasOwnProperty.call(PROVIDER_DEFAULT_MODEL, name);
+
+async function queryRemoteModels(
+  url: string,
+  apiKey: string | undefined,
+  signal: AbortSignal,
+  fetchModels: FetchModels = fetch,
+  timeoutMs = MODEL_LOOKUP_TIMEOUT_MS,
+): Promise<string[]> {
+  if (signal.aborted) throw new Error('provider lookup cancelled');
+  const controller = new AbortController();
+  let rejectCancelled: ((reason: Error) => void) | undefined;
+  const cancelled = new Promise<never>((_, reject) => { rejectCancelled = reject; });
+  const cancel = (): void => {
+    controller.abort();
+    rejectCancelled?.(new Error('provider lookup cancelled'));
+  };
+  signal.addEventListener('abort', cancel, { once: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    if (signal.aborted) throw new Error('provider lookup cancelled');
+    const deadline = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error('remote model lookup timed out'));
+        controller.abort();
+      }, timeoutMs);
+    });
+    const request = (async () => {
+      const response = await fetchModels(url, {
+        signal: controller.signal,
+        headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      });
+      if (!response.ok) throw new Error(`remote model lookup HTTP ${response.status}`);
+      const payload = await response.json() as unknown;
+      if (!payload || typeof payload !== 'object' || !('data' in payload) || !Array.isArray(payload.data)
+        || payload.data.some((entry: unknown) => !entry || typeof entry !== 'object'
+          || !('id' in entry) || typeof entry.id !== 'string' || entry.id.trim().length === 0)) {
+        throw new Error('remote model list is malformed');
+      }
+      const ids = [...new Set(payload.data.map((entry: { id: string }) => entry.id))].sort();
+      if (ids.length === 0) throw new Error('remote model list is empty');
+      return ids;
+    })();
+    return await Promise.race([request, deadline, cancelled]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    signal.removeEventListener('abort', cancel);
+  }
+}
+
+function remoteModelsUrl(provider: string, baseUrl: string | undefined): string | undefined {
+  if (baseUrl) {
+    const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const url = new URL('models', base);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('invalid base URL');
+    return url.toString();
+  }
+  return provider === 'openrouter' ? 'https://openrouter.ai/api/v1/models' : undefined;
+}
+
+async function setProviderViaCli(provider: string, model: string | undefined, signal: AbortSignal): Promise<void> {
+  const cli = process.argv[1];
+  if (!cli) throw new Error('elanous CLI entry is unavailable');
+  const child = Bun.spawn({
+    cmd: [process.execPath, cli, 'provider:set', provider, ...(model ? ['--model', model] : [])],
+    stdin: 'ignore', stdout: 'pipe', stderr: 'pipe', env: process.env,
+  });
+  const abort = (): void => { child.kill(); };
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) abort();
+  try {
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited,
+    ]);
+    if (signal.aborted) throw new Error('provider switch cancelled');
+    if (code !== 0) throw new Error(stderr.trim().split('\n').at(-1) || stdout.trim().split('\n').at(-1) || `provider:set exit ${code}`);
+    reloadUserConfig();
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+}
+
+export async function runLocalProviderCommand(
+  raw: string,
+  signal: AbortSignal,
+  onLine: (line: string) => void,
+): Promise<void> {
+  if (signal.aborted) throw new Error('provider lookup cancelled');
+  const [action, providerArg, modelArg] = raw.trim() ? raw.trim().split(/\s+/) : ['list'];
+  const cfg = getUserConfig().llm;
+  const current = cfg.provider;
+  if (action === 'list') {
+    onLine(`현재: ${current}/${cfg.model || PROVIDER_DEFAULT_MODEL[current] || '기본 모델'}`);
+    for (const [name, model] of Object.entries(PROVIDER_DEFAULT_MODEL)) {
+      if (name === 'auto') continue;
+      onLine(`${name === current ? '●' : '○'} ${name} · ${model || '기본 모델'}`);
+    }
+    onLine('모델: /provider models [provider] · /provider refresh [provider]');
+    onLine('전환: /provider use <provider> [model]');
+    return;
+  }
+  if (action === 'models' || action === 'refresh') {
+    const provider = providerArg || current;
+    if (!supportedProvider(provider)) throw new Error(`알 수 없는 provider: ${provider}`);
+    let url: string | undefined;
+    let urlError: string | undefined;
+    try {
+      url = provider === current ? remoteModelsUrl(provider, cfg.baseUrl) : remoteModelsUrl(provider, undefined);
+    } catch {
+      urlError = 'invalid base URL';
+    }
+    const result = await cache.models(provider, url, provider === current ? cfg.apiKey : undefined, signal, action === 'refresh');
+    const note = urlError ?? result.note;
+    onLine(`${provider} 모델 · ${result.source}${note ? ` (조회 실패: ${note})` : ''}`);
+    for (const id of result.ids.slice(0, MODEL_DISPLAY_LIMIT)) onLine(`  ${id}`);
+    if (result.ids.length > MODEL_DISPLAY_LIMIT) onLine(`  외 ${result.ids.length - MODEL_DISPLAY_LIMIT}개`);
+    if (result.ids.length === 0) onLine('  목록 없음 · /provider use <provider> <model>로 직접 지정 가능');
+    return;
+  }
+  if (action === 'use') {
+    if (!providerArg || !supportedProvider(providerArg)) {
+      throw new Error('사용법: /provider use <provider> [model]');
+    }
+    await setProviderViaCli(providerArg, modelArg, signal);
+    const next = getUserConfig().llm;
+    onLine(`다음 턴 provider: ${next.provider}/${next.model || '기본 모델'}`);
+    return;
+  }
+  throw new Error('사용법: /provider · /provider models [provider] · /provider use <provider> [model]');
+}

package/src/tui-client/next-dashboard-runtime.ts

@@ -0,0 +1,8 @@
+/** Dashboard integrations used by next TUI, loaded only after that surface is opened. */
+export async function loadNextTuiDashboardRuntime() {
+  const [segments, goalContinue] = await Promise.all([
+    import('../dashboard/turn-start-segments.js'),
+    import('../dashboard/input/goal-continue.js'),
+  ]);
+  return { ...segments, ...goalContinue };
+}

package/src/tui-client/next-loop-command.ts

@@ -0,0 +1,70 @@
+import { createLoopScheduler, type LoopScheduler } from '../dashboard/loop-scheduler.js';
+import type { InternalTurnGate } from '../dashboard/input/internal-turn.js';
+
+export interface NextLoopCommand {
+  run(raw: string): string[];
+  dispose(): void;
+}
+
+export interface NextLoopCommandOptions {
+  schedule?: (callback: () => void, intervalMs: number) => { unsubscribe(): void };
+}
+
+function parseInterval(raw: string): { intervalMs: number; label: string } | null {
+  const match = /^(\d+)(s|sec|초|m|min|분|h|시간)?$/i.exec(raw.trim());
+  if (!match) return null;
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount <= 0) return null;
+  const unit = (match[2] ?? 'm').toLowerCase();
+  const intervalMs = unit === 's' || unit === 'sec' || unit === '초' ? amount * 1_000
+    : unit === 'h' || unit === '시간' ? amount * 3_600_000
+    : amount * 60_000;
+  // Node/Bun timers clamp delays above 2^31-1ms and can then fire almost immediately.
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 1_000 || intervalMs > 2_147_483_647) return null;
+  const label = unit === 's' || unit === 'sec' || unit === '초' ? `${amount}초`
+    : unit === 'h' || unit === '시간' ? `${amount}시간`
+    : `${amount}분`;
+  return { intervalMs, label };
+}
+
+/** Next TUI's `/loop` surface; H2 decides whether each scheduled turn may open. */
+export function createNextLoopCommand(
+  gate: InternalTurnGate,
+  log: (event: 'fired' | 'rejected', data: Record<string, unknown>) => void,
+  options: NextLoopCommandOptions = {},
+): NextLoopCommand {
+  let scheduler: LoopScheduler | null = null;
+  const stop = (): boolean => {
+    if (!scheduler?.isRunning()) return false;
+    scheduler.stop();
+    scheduler = null;
+    return true;
+  };
+  return {
+    run(raw) {
+      const [interval = '', ...promptParts] = raw.trim().split(/\s+/);
+      const sub = interval.toLowerCase();
+      if (!interval || sub === 'help') {
+        return ['usage: /loop <간격> <프롬프트> · /loop stop', '간격: 30s · 5m · 1h · 맨숫자=분 — TUI가 쉴 때 프롬프트를 발사합니다'];
+      }
+      if (sub === 'stop') return [stop() ? '⏹ /loop 정지 — 더 이상 발사하지 않습니다' : '/loop: 실행 중인 루프가 없습니다'];
+      const parsed = parseInterval(interval);
+      const prompt = promptParts.join(' ').trim();
+      if (!parsed || !prompt) return ['사용법: /loop <간격> <프롬프트> · /loop stop'];
+      stop();
+      scheduler = createLoopScheduler({
+        intervalMs: parsed.intervalMs,
+        isIdle: () => true,
+        ...(options.schedule ? { schedule: options.schedule } : {}),
+        fire: () => {
+          const result = gate.startTurnIfIdle(prompt, { origin: 'scheduled', reason: '/loop' });
+          if (result.opened) log('fired', { turnId: result.turnId });
+          else log('rejected', { reason: result.reason });
+        },
+      });
+      scheduler.start();
+      return [`↻ /loop 시작 — ${parsed.label}마다: ${prompt}`];
+    },
+    dispose: stop,
+  };
+}