@opencoven/coven-code 0.0.1

package/src/cli/interactive-core.mjs

@@ -0,0 +1,302 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { appendFile, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { AGENT_MODES, CLI_NAME, CONFIG_SUBDIR, REPL_HISTORY_LIMIT } from '../constants.mjs';
+import { configDir } from '../settings/paths.mjs';
+import { shellQuote, splitShellWords } from '../util/shell.mjs';
+import { latestActiveThread, requireThread } from '../threads/store.mjs';
+import { runCommand } from './dispatch.mjs';
+import { runExecute } from './execute.mjs';
+import {
+  coerceReasoningEffortForMode,
+  nextReasoningEffortForMode,
+  reasoningEffortForMode,
+} from './reasoning.mjs';
+import {
+  buildSlashCommandCatalog,
+  findSlashCommand,
+  formatSlashCommandDetails,
+  formatSlashHelpLines,
+  skillPromptFromSlashCommand,
+} from './slash-commands.mjs';
+
+export function createInteractiveSession(parsed, options = {}) {
+  return {
+    parsed,
+    thread: options.thread,
+    cwd: options.cwd ?? process.cwd(),
+    queuedMessages: [],
+    commandRunner: options.commandRunner ?? runCommand,
+    executeRunner: options.executeRunner ?? runExecute,
+    editorReader: options.editorReader ?? readEditorPrompt,
+  };
+}
+
+export async function handleInteractiveInput(session, text) {
+  if (!text) return { kind: 'empty', lines: [] };
+  if (text === '/exit' || text === '/quit') return { kind: 'exit', lines: [] };
+  if (text === '/help') return { kind: 'help', lines: await sessionSlashHelpLines(session) };
+  if (!text.startsWith('/')) {
+    session.thread = await runInteractiveTurn(session.parsed, text, session.thread, session.executeRunner);
+    while (session.queuedMessages.length > 0) {
+      session.thread = await runInteractiveTurn(session.parsed, session.queuedMessages.shift(), session.thread, session.executeRunner);
+    }
+    return { kind: 'turn', lines: [] };
+  }
+
+  const tokens = splitShellWords(text.slice(1));
+  const [cmd, ...rest] = tokens;
+  const catalog = await safeSlashCommandCatalog(session);
+  if (!cmd) return { kind: 'help', lines: formatCatalogHelpLines(catalog) };
+  const catalogEntry = findSlashCommand(catalog, cmd);
+
+  if (catalogEntry?.source === 'skill') {
+    if (rest.length === 0) {
+      return { kind: 'command', lines: formatSlashCommandDetails(catalogEntry) };
+    }
+    await submitPromptAndQueue(session, skillPromptFromSlashCommand(catalogEntry, rest.join(' ')));
+    return { kind: 'turn', lines: [] };
+  }
+
+  if (catalogEntry?.source === 'plugin' && catalogEntry.availability?.type === 'disabled') {
+    return {
+      kind: 'error',
+      lines: [`${CLI_NAME}: ${catalogEntry.availability.reason ?? `Plugin command disabled: ${catalogEntry.name}`}`],
+    };
+  }
+
+  if (cmd === 'mode') {
+    const nextMode = rest[0];
+    if (!nextMode) return { kind: 'command', lines: [`mode: ${session.parsed.mode}`] };
+    if (!AGENT_MODES.includes(nextMode)) return { kind: 'error', lines: [`${CLI_NAME}: Unknown mode: ${nextMode}`] };
+    session.parsed.mode = nextMode;
+    session.parsed.reasoningEffort = coerceReasoningEffortForMode(session.parsed.mode, session.parsed.reasoningEffort);
+    return { kind: 'command', lines: [`mode: ${session.parsed.mode}`, `reasoning effort: ${session.parsed.reasoningEffort}`] };
+  }
+
+  if (cmd === 'reasoning') {
+    try {
+      const nextEffort = rest[0] === 'next'
+        ? nextReasoningEffortForMode(session.parsed.mode, session.parsed.reasoningEffort)
+        : rest[0];
+      session.parsed.reasoningEffort = reasoningEffortForMode(session.parsed.mode, nextEffort ?? session.parsed.reasoningEffort);
+      return { kind: 'command', lines: [`reasoning effort: ${session.parsed.reasoningEffort}`] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  if (cmd === 'queue') {
+    const queued = rest.join(' ').trim();
+    if (!queued) return { kind: 'error', lines: [`${CLI_NAME}: /queue requires a prompt`] };
+    session.queuedMessages.push(queued);
+    return { kind: 'command', lines: [`queued: ${queued}`] };
+  }
+
+  if (cmd === 'new') {
+    session.thread = undefined;
+    return { kind: 'command', lines: ['new thread'] };
+  }
+
+  if (cmd === 'continue') {
+    try {
+      session.thread = interactiveContinuationThread(rest[0]);
+      return { kind: 'command', lines: [`continued: ${session.thread.id}`] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  if (cmd === `${CLI_NAME}:` && rest.join(' ') === 'help') return { kind: 'help', lines: await sessionSlashHelpLines(session) };
+
+  if (cmd === 'editor') {
+    const edited = await session.editorReader();
+    if (edited) await submitPromptAndQueue(session, edited);
+    return { kind: 'command', lines: [] };
+  }
+
+  if (cmd === 'edit') {
+    try {
+      if (!session.thread) throw new Error('No current thread to edit');
+      const editTarget = editablePreviousPrompt(session.thread);
+      const edited = await session.editorReader(editTarget.prompt);
+      if (edited) {
+        session.thread.messages = session.thread.messages.slice(0, editTarget.index);
+        if (session.thread.messages.length === 0) {
+          session.thread.title = edited.split(/\r?\n/).find(Boolean)?.slice(0, 120) || '(empty prompt)';
+        }
+        await submitPromptAndQueue(session, edited);
+      }
+      return { kind: 'command', lines: [] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  if (cmd === 'thread:' && rest.join(' ') === 'archive and quit') {
+    try {
+      if (!session.thread) throw new Error('No current thread to archive');
+      await session.commandRunner('threads', ['archive', session.thread.id], session.parsed, '');
+      return { kind: 'exit', lines: [] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  if (cmd === 'thread:' && rest[0] === 'set' && rest[1] === 'visibility') {
+    try {
+      if (!session.thread) throw new Error('No current thread to update');
+      await session.commandRunner('threads', ['visibility', session.thread.id, ...rest.slice(2)], session.parsed, '');
+      return { kind: 'command', lines: [] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  if (cmd === 'feedback:' && rest.join(' ') === 'send report with diagnostics') {
+    try {
+      if (!session.thread) throw new Error('No current thread to report');
+      await session.commandRunner('threads', ['report', session.thread.id], session.parsed, '');
+      return { kind: 'command', lines: [] };
+    } catch (error) {
+      return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+    }
+  }
+
+  try {
+    if (cmd === 'skill:') await session.commandRunner('skill', rest, session.parsed, '');
+    else if (cmd === 'plugins:') await session.commandRunner('plugins', rest, session.parsed, '');
+    else await session.commandRunner(cmd, rest, session.parsed, '');
+    return { kind: 'command', lines: [] };
+  } catch (error) {
+    if (String(error?.message ?? '').startsWith('Unknown command:')) {
+      try {
+        await session.commandRunner('plugins', ['run', cmd], session.parsed, '');
+        return { kind: 'command', lines: [] };
+      } catch (pluginError) {
+        if (!String(pluginError?.message ?? '').startsWith('Unknown plugin command:')) throw pluginError;
+      }
+    }
+    return { kind: 'error', lines: [`${CLI_NAME}: ${error?.message ?? error}`] };
+  }
+}
+
+async function submitPromptAndQueue(session, text) {
+  session.thread = await runInteractiveTurn(session.parsed, text, session.thread, session.executeRunner);
+  while (session.queuedMessages.length > 0) {
+    session.thread = await runInteractiveTurn(session.parsed, session.queuedMessages.shift(), session.thread, session.executeRunner);
+  }
+}
+
+export function slashHelpLines() {
+  return formatSlashHelpLines();
+}
+
+export function printSlashHelp() {
+  for (const line of slashHelpLines()) console.log(line);
+}
+
+export async function readEditorPrompt(initialText = '') {
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    console.error(`${CLI_NAME}: /editor requires $EDITOR or $VISUAL`);
+    return '';
+  }
+  const file = path.join(tmpdir(), `${CONFIG_SUBDIR}-prompt-${process.pid}-${Date.now()}.md`);
+  try {
+    await writeFile(file, initialText);
+    const result = spawnSync(`${editor} ${shellQuote(file)}`, {
+      stdio: 'inherit',
+      shell: true,
+    });
+    if (result.error) {
+      console.error(`${CLI_NAME}: Unable to run editor: ${result.error.message}`);
+      return '';
+    }
+    if ((result.status ?? 0) !== 0) {
+      console.error(`${CLI_NAME}: Editor exited with status ${result.status}`);
+      return '';
+    }
+    return (await readFile(file, 'utf8')).trim();
+  } finally {
+    await unlink(file).catch(() => {});
+  }
+}
+
+export function editablePreviousPrompt(thread) {
+  const index = (thread.messages ?? []).findLastIndex((message) => (
+    message.role === 'user' && typeof message.content === 'string'
+  ));
+  if (index === -1) throw new Error('No previous user prompt to edit');
+  return { index, prompt: thread.messages[index].content };
+}
+
+export function interactiveContinuationThread(threadId) {
+  if (threadId) return requireThread(threadId);
+  const thread = latestActiveThread();
+  if (!thread) throw new Error('No active thread to continue');
+  return thread;
+}
+
+export async function runInteractiveTurn(parsed, text, thread, executeRunner = runExecute) {
+  try {
+    return await executeRunner(
+      { ...parsed, execute: true, prompt: text, streamJson: false, streamJsonThinking: false, streamJsonInput: false },
+      '',
+      { thread },
+    );
+  } catch (error) {
+    console.error(`${CLI_NAME}: ${error?.message ?? error}`);
+    return thread;
+  }
+}
+
+export function replHistoryFile() {
+  return process.env.COVEN_CODE_REPL_HISTORY_FILE
+    || path.join(configDir(), CONFIG_SUBDIR, 'repl_history');
+}
+
+export function loadReplHistory() {
+  if (process.env.COVEN_CODE_REPL_HISTORY === '0') return [];
+  try {
+    return readFileSync(replHistoryFile(), 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(-REPL_HISTORY_LIMIT)
+      .reverse();
+  } catch {
+    return [];
+  }
+}
+
+export async function appendReplHistory(line) {
+  if (process.env.COVEN_CODE_REPL_HISTORY === '0') return;
+  try {
+    const file = replHistoryFile();
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, `${line}\n`);
+  } catch {
+    // history must never break the REPL
+  }
+}
+
+async function safeSlashCommandCatalog(session) {
+  try {
+    return await buildSlashCommandCatalog({
+      parsed: session.parsed,
+      cwd: session.cwd ?? process.cwd(),
+    });
+  } catch {
+    return [];
+  }
+}
+
+async function sessionSlashHelpLines(session) {
+  return formatCatalogHelpLines(await safeSlashCommandCatalog(session));
+}
+
+function formatCatalogHelpLines(catalog) {
+  return catalog.length > 0 ? formatSlashHelpLines(catalog) : slashHelpLines();
+}

package/src/cli/notifications.mjs

@@ -0,0 +1,13 @@
+import { readEffectiveSettings } from '../settings/load.mjs';
+
+export function notifyAgentComplete(parsed = {}) {
+  if (readEffectiveSettings(parsed)['covenCode.notifications.enabled'] === false) return;
+  if (!shouldUseTerminalBell()) return;
+  process.stderr.write('\x07');
+}
+
+function shouldUseTerminalBell() {
+  return process.env.COVEN_CODE_FORCE_BEL === '1'
+    || process.env.COVEN_CODE_FORCE_BEL === 'true'
+    || Boolean(process.env.SSH_TTY || process.env.SSH_CONNECTION);
+}

package/src/cli/parse.mjs

@@ -0,0 +1,83 @@
+export class UsageError extends Error {}
+
+export function parseGlobalArgs(args) {
+  const parsed = {
+    execute: false,
+    prompt: '',
+    streamJson: false,
+    streamJsonThinking: false,
+    streamJsonInput: false,
+    dangerouslyAllowAll: false,
+    help: false,
+    version: false,
+    mode: 'smart',
+    reasoningEffort: undefined,
+    mcpConfig: undefined,
+    settingsFile: undefined,
+    labels: [],
+    visibility: undefined,
+    archive: false,
+    continueThread: false,
+    toolbox: undefined,
+    skills: undefined,
+    ide: undefined,
+    positionals: [],
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h') parsed.help = true;
+    else if (arg === '--version' || arg === '-v') parsed.version = true;
+    else if (arg === '--execute' || arg === '-x') {
+      parsed.execute = true;
+      const next = args[index + 1];
+      if (next && !next.startsWith('-')) {
+        parsed.prompt = next;
+        index += 1;
+      }
+    } else if (arg === '--stream-json') parsed.streamJson = true;
+    else if (arg === '--stream-json-thinking') {
+      parsed.streamJson = true;
+      parsed.streamJsonThinking = true;
+    } else if (arg === '--stream-json-input') parsed.streamJsonInput = true;
+    else if (arg === '--dangerously-allow-all') parsed.dangerouslyAllowAll = true;
+    else if (arg === '--mcp-config') {
+      parsed.mcpConfig = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--settings-file') {
+      parsed.settingsFile = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--label') {
+      parsed.labels.push(args[index + 1] ?? '');
+      index += 1;
+    } else if (arg === '--visibility') {
+      parsed.visibility = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--archive') {
+      parsed.archive = true;
+    } else if (arg === '--continue') {
+      const next = args[index + 1];
+      if (next && /^T-[A-Za-z0-9-]+$/.test(next)) {
+        parsed.continueThread = next;
+        index += 1;
+      } else {
+        parsed.continueThread = true;
+      }
+    } else if (arg === '--toolbox') {
+      parsed.toolbox = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--skills') {
+      parsed.skills = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--mode') {
+      parsed.mode = args[index + 1] ?? parsed.mode;
+      index += 1;
+    } else if (arg === '--reasoning-effort') {
+      parsed.reasoningEffort = args[index + 1] ?? '';
+      index += 1;
+    } else if (arg === '--jetbrains') parsed.ide = 'jetbrains';
+    else parsed.positionals.push(arg);
+  }
+
+  return parsed;
+}

package/src/cli/reasoning.mjs

@@ -0,0 +1,45 @@
+import { UsageError } from './parse.mjs';
+
+const DEFAULT_REASONING_EFFORT_BY_MODE = {
+  smart: 'high',
+  deep: 'high',
+  rush: 'minimal',
+  large: 'high',
+};
+
+const REASONING_EFFORTS_BY_MODE = {
+  smart: ['high', 'xhigh', 'max'],
+  deep: ['high', 'low', 'medium', 'xhigh'],
+  rush: ['minimal'],
+  large: ['high', 'xhigh', 'max'],
+};
+
+export function reasoningEffortForMode(mode, requested) {
+  const efforts = reasoningEffortsForMode(mode);
+  if (requested === undefined || requested === null || requested === '') return defaultReasoningEffortForMode(mode);
+  if (efforts.includes(requested)) return requested;
+  throw new UsageError(`reasoning effort for ${mode} must be one of: ${efforts.join(', ')}`);
+}
+
+export function coerceReasoningEffortForMode(mode, requested) {
+  try {
+    return reasoningEffortForMode(mode, requested);
+  } catch {
+    return defaultReasoningEffortForMode(mode);
+  }
+}
+
+export function nextReasoningEffortForMode(mode, requested) {
+  const efforts = reasoningEffortsForMode(mode);
+  const current = coerceReasoningEffortForMode(mode, requested);
+  const index = efforts.indexOf(current);
+  return efforts[(index + 1) % efforts.length];
+}
+
+function defaultReasoningEffortForMode(mode) {
+  return DEFAULT_REASONING_EFFORT_BY_MODE[mode] ?? DEFAULT_REASONING_EFFORT_BY_MODE.smart;
+}
+
+function reasoningEffortsForMode(mode) {
+  return REASONING_EFFORTS_BY_MODE[mode] ?? REASONING_EFFORTS_BY_MODE.smart;
+}

package/src/cli/refs.mjs

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { FILE_MENTION_MAX_LINES, FILE_MENTION_MAX_LINE_LENGTH, THREAD_URL_BASE } from '../constants.mjs';
+import { globToRegex, hasGlob, walkFiles } from '../util/glob.mjs';
+import { listThreads, readThread, threadSearchText } from '../threads/store.mjs';
+import { readEffectiveSettings } from '../settings/load.mjs';
+
+export function expandFileReferences(prompt, options = {}) {
+  return prompt.replace(/@(?!(?:T-|@))((?:~|\/|\.{1,2}\/)?[A-Za-z0-9_./*?-]*[A-Za-z0-9_*-])/g, (match, rawPath) => {
+    const blocks = mentionedFiles(rawPath, options)
+      .map((filePath) => fileMentionBlock(filePath, options))
+      .filter(Boolean);
+    if (blocks.length === 0) return match;
+    return blocks.join('\n');
+  });
+}
+
+function fileMentionBlock(filePath, options = {}) {
+  const image = imageMentionBlock(filePath);
+  if (image) return image;
+  const content = readMentionedTextFile(filePath);
+  if (content === undefined) return undefined;
+  if (options.includeFile && !options.includeFile(filePath, content)) return undefined;
+  return `[file:${filePath}]\n${content}\n[/file]`;
+}
+
+export function imageMentionBlock(filePath) {
+  const mediaType = imageMediaType(filePath);
+  if (!mediaType) return undefined;
+  const bytes = readFileSync(filePath).byteLength;
+  return `[image:${filePath}]\nmedia_type: ${mediaType}\nbytes: ${bytes}\n[/image]`;
+}
+
+function imageMediaType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.png') return 'image/png';
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.webp') return 'image/webp';
+  return undefined;
+}
+
+function readMentionedTextFile(filePath) {
+  const raw = readFileSync(filePath);
+  if (raw.includes(0)) return undefined;
+  const text = raw.toString('utf8');
+  return text
+    .split(/\r?\n/)
+    .slice(0, FILE_MENTION_MAX_LINES)
+    .map((line) => line.slice(0, FILE_MENTION_MAX_LINE_LENGTH))
+    .join('\n');
+}
+
+function mentionedFiles(rawPath, options = {}) {
+  if (!hasGlob(rawPath)) {
+    const filePath = resolveMentionedPath(rawPath, options);
+    return existsSync(filePath) && statSync(filePath).isFile() ? [filePath] : [];
+  }
+  const root = globSearchRoot(rawPath, options);
+  const pattern = rawPath.startsWith('~/')
+    ? path.join(os.homedir(), rawPath.slice(2))
+    : path.resolve(options.baseDir ?? process.cwd(), rawPath);
+  const re = globToRegex(path.normalize(pattern));
+  const ignored = gitignoredFileMatcher(options.baseDir ?? process.cwd());
+  const alwaysIncluded = alwaysIncludedFileMatcher(options.baseDir ?? process.cwd(), options.parsed);
+  return walkFiles(root)
+    .filter((filePath) => re.test(path.normalize(filePath)))
+    .filter((filePath) => !ignored(filePath) || alwaysIncluded(filePath))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function resolveMentionedPath(rawPath, options = {}) {
+  if (rawPath.startsWith('~/')) return path.join(os.homedir(), rawPath.slice(2));
+  if (path.isAbsolute(rawPath)) return rawPath;
+  return path.resolve(options.baseDir ?? process.cwd(), rawPath);
+}
+
+function globSearchRoot(rawPath, options = {}) {
+  const pattern = resolveMentionedPath(rawPath, options);
+  const parts = pattern.split(path.sep);
+  const stableParts = [];
+  for (const part of parts) {
+    if (hasGlob(part)) break;
+    stableParts.push(part);
+  }
+  const root = stableParts.join(path.sep) || path.sep;
+  return existsSync(root) && statSync(root).isDirectory() ? root : path.dirname(root);
+}
+
+function gitignoredFileMatcher(baseDir) {
+  const gitignorePath = findUp('.gitignore', baseDir);
+  if (!gitignorePath) return () => false;
+  const root = path.dirname(gitignorePath);
+  const patterns = readFileSync(gitignorePath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#') && !line.startsWith('!'))
+    .map((line) => gitignorePatternRegex(root, line));
+  return (filePath) => patterns.some((pattern) => pattern.test(path.normalize(filePath)));
+}
+
+function alwaysIncludedFileMatcher(baseDir, parsed = {}) {
+  const settings = readEffectiveSettings(parsed);
+  const patterns = Array.isArray(settings['covenCode.fuzzy.alwaysIncludePaths'])
+    ? settings['covenCode.fuzzy.alwaysIncludePaths']
+    : [];
+  const root = path.dirname(findUp('.gitignore', baseDir) ?? path.join(path.resolve(baseDir), '.gitignore'));
+  const regexes = patterns
+    .filter((pattern) => typeof pattern === 'string' && pattern.trim())
+    .map((pattern) => globToRegex(path.normalize(path.resolve(root, pattern))));
+  return (filePath) => regexes.some((pattern) => pattern.test(path.normalize(filePath)));
+}
+
+function gitignorePatternRegex(root, pattern) {
+  const directoryOnly = pattern.endsWith('/');
+  const cleanPattern = pattern.replace(/\/+$/, '');
+  const absolutePattern = path.resolve(root, cleanPattern);
+  const source = directoryOnly
+    ? `${globToRegex(path.normalize(absolutePattern)).source.slice(1, -1)}(?:${escapePathSep()}.*)?`
+    : globToRegex(path.normalize(absolutePattern)).source.slice(1, -1);
+  return new RegExp(`^${source}$`);
+}
+
+function escapePathSep() {
+  return path.sep === '\\' ? '\\\\' : '/';
+}
+
+function findUp(name, cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(current, name);
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current || current === os.homedir()) return undefined;
+    current = parent;
+  }
+}
+
+export function expandThreadReferences(prompt) {
+  const threadUrlPattern = THREAD_URL_BASE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const explicitReferences = prompt.replace(new RegExp(`(?:@|${threadUrlPattern}/)(T-[A-Za-z0-9-]+)`, 'g'), (match, threadId) => {
+    const thread = readThread(threadId);
+    if (!thread) return match;
+    return threadMentionBlock(thread);
+  });
+  return explicitReferences.replace(/@@([A-Za-z0-9_.:/-]+)/g, (match, rawQuery) => {
+    const thread = findMentionedThread(rawQuery);
+    return thread ? threadMentionBlock(thread) : match;
+  });
+}
+
+function findMentionedThread(rawQuery) {
+  const query = String(rawQuery ?? '').trim().toLowerCase();
+  if (!query) return undefined;
+  return listThreads()
+    .filter((thread) => threadSearchText(thread).toLowerCase().includes(query))[0];
+}
+
+function threadMentionBlock(thread) {
+  return `[thread:${thread.id}]\n${thread.messages.map((message) => `${message.role}: ${message.content}`).join('\n')}\n[/thread]`;
+}

package/src/cli/repl.mjs

@@ -0,0 +1,61 @@
+import * as readline from 'node:readline/promises';
+import { CLI_NAME, REPL_HISTORY_LIMIT, VERSION } from '../constants.mjs';
+import {
+  appendReplHistory,
+  createInteractiveSession,
+  handleInteractiveInput,
+  loadReplHistory,
+} from './interactive-core.mjs';
+
+export async function runInteractive(parsed, initialInput = '') {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+    historySize: REPL_HISTORY_LIMIT,
+    removeHistoryDuplicates: true,
+    history: loadReplHistory(),
+  });
+  const session = createInteractiveSession(parsed);
+  let buffer = [];
+  console.log(`${CLI_NAME} ${VERSION} — interactive mode. Type /exit or press Ctrl-D to quit, /help for slash commands.`);
+  if (initialInput.trim()) {
+    await handleInteractiveInput(session, initialInput.trim());
+    if (!process.stdin.isTTY) {
+      rl.close();
+      return;
+    }
+  }
+  rl.setPrompt('> ');
+  rl.prompt();
+  try {
+    for await (const line of rl) {
+      if (line.trim()) await appendReplHistory(line);
+      if (line.endsWith('\\')) {
+        buffer.push(line.slice(0, -1));
+        rl.setPrompt('… ');
+        rl.prompt();
+        continue;
+      }
+      buffer.push(line);
+      const text = buffer.join('\n').trim();
+      buffer = [];
+      rl.setPrompt('> ');
+      if (!text) {
+        rl.prompt();
+        continue;
+      }
+      const result = await handleInteractiveInput(session, text);
+      if (result.lines.length > 0) {
+        for (const outputLine of result.lines) {
+          if (result.kind === 'error') console.error(outputLine);
+          else console.log(outputLine);
+        }
+      }
+      if (result.kind === 'exit') break;
+      rl.prompt();
+    }
+  } finally {
+    rl.close();
+  }
+}