@easynet/agent-runtime 1.0.2 → 1.0.4

package/src/cli.ts

@@ -2,741 +2,130 @@
  * Shared CLI runner for agent apps.
  * Provides: arg parsing, single-shot mode, interactive REPL, event logging.
  */
-import os from "node:os";
-import { createInterface } from "node:readline";
-import MarkdownIt from "markdown-it";
-import markdownItTerminal from "markdown-it-terminal";
-import {
-  createConsoleAgentEventListener,
-  type AgentEvent,
-  type AgentEventListener,
-} from "@easynet/agent-common";
-import { createReactAgent, type ReactAgentRuntime } from "./react-agent.js";
-import { createDeepAgent, type DeepAgentRuntime } from "./deep-agent.js";
-import { malformedToolCallMiddleware } from "./malformed-tool-call-middleware.js";
-import type { BotContext } from "./context.js";
-
-const REACT = "react" as const;
-const DEEP = "deep" as const;
-
-type AgentKind = typeof REACT | typeof DEEP;
-
-export interface AppCliUiOptions {
-  /** Prompt/section label for user. Default: current OS user (username(uid)). */
-  userLabel?: string;
-  /** Prompt/section label for assistant. Default: agent kind (ReAct/Deep). */
-  assistantLabel?: string;
-  /** Enable ANSI colors in interactive output. Default: true when TTY and NO_COLOR is not set. */
-  useColor?: boolean;
-  /** Render assistant output as terminal-friendly markdown. Default: true. */
-  renderMarkdown?: boolean;
-  /** Echo the user question in the response section. Default: true. */
-  echoUserQuestion?: boolean;
-  /** Startup loading line. Set false to suppress. */
-  loadingText?: string | false;
-  /** Show animated loading progress while creating bot context. */
-  loadingSpinner?: boolean;
-  /** Startup ready line. Set false to suppress. */
-  readyText?: string | false;
-  /** Interactive intro line before prompt. Set false to suppress. */
-  interactiveIntro?: string | false;
-  /** Show animated spinner while a user request is being processed. */
-  processingSpinner?: boolean;
-  /** Spinner label shown while processing. Set false to suppress label/spinner. */
-  processingText?: string | false;
-}
-
-export interface AppCliOptions {
-  appName: string;
-  createBotContext: () => Promise<BotContext>;
-  /** Extra interactive commands, e.g. { "list tools": (ctx) => ... } */
-  interactiveCommands?: Record<string, (ctx: BotContext) => void | Promise<void>>;
-  /** Extra event listener(s) for structured runtime logs. */
-  eventListener?: AgentEventListener | AgentEventListener[];
-  /** Called after context is ready, before the REPL starts. Failures are logged but do not crash. */
-  onReady?: (ctx: BotContext) => void | Promise<void>;
-  /** Called during shutdown (exit/signal). Should be synchronous and fast. */
-  onShutdown?: (ctx: BotContext) => void;
-  /** Interactive UI style options. */
-  ui?: AppCliUiOptions;
-}
-
-function parseArgs(): { kind: AgentKind; query?: string } {
-  const args = process.argv.slice(2);
-  const first = args[0]?.toLowerCase();
-  const kind: AgentKind = first === DEEP ? DEEP : REACT;
-  const query =
-    first === REACT || first === DEEP ? (args[1] ?? undefined) : (first ?? undefined);
-  return { kind, query };
-}
-
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-async function createRuntime(
-  ctx: BotContext,
-  kind: AgentKind
-): Promise<ReactAgentRuntime | DeepAgentRuntime> {
-  if (kind === REACT) {
-    return createReactAgent(ctx, {
-      middleware: [malformedToolCallMiddleware()],
-    });
-  }
-  return createDeepAgent(ctx);
-}
-
-async function runOne(ctx: BotContext, kind: AgentKind, query: string): Promise<string> {
-  const runtime = await createRuntime(ctx, kind);
-  const { text } = await runtime.run(query);
-  return text;
-}
-
-function createAnsi(useColor: boolean): Record<string, string> {
-  return {
-    reset: useColor ? "\x1b[0m" : "",
-    dim: useColor ? "\x1b[2m" : "",
-    heading: useColor ? "\x1b[1;38;5;45m" : "",
-    bullet: useColor ? "\x1b[38;5;81m" : "",
-    code: useColor ? "\x1b[38;5;221m" : "",
-    quote: useColor ? "\x1b[38;5;245m" : "",
-    hr: useColor ? "\x1b[38;5;240m" : "",
+import { createConsoleAgentEventListener } from "@easynet/agent-common";
+import { parseArgs } from "./cli/args.js";
+import { createStructuredRunEventListener } from "./cli/event-listener.js";
+import { interactive } from "./cli/interactive.js";
+import { readDefaultAgentKindFromConfig, runOne } from "./cli/runtime.js";
+import { startLoadingSpinner } from "./cli/spinner.js";
+import { renderForTerminal } from "./cli/terminal-render.js";
+import { REACT, type AgentKind, type AppCliOptions, type AppCliUiOptions } from "./cli/types.js";
+
+export type { AppCliOptions, AppCliUiOptions };
+export { createStructuredRunEventListener };
+
+function createExitHandler(
+  appName: string,
+  onShutdown: AppCliOptions["onShutdown"],
+  ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>,
+): (code: number) => never {
+  let didCleanup = false;
+
+  const cleanup = () => {
+    if (didCleanup) return;
+    didCleanup = true;
+    try {
+      onShutdown?.(ctx);
+    } catch (err) {
+      console.error(`${appName}: onShutdown hook failed:`, err instanceof Error ? err.message : err);
+    }
   };
-}
-
-function styleInlineMarkdown(line: string, ansi: Record<string, string>): string {
-  return line
-    .replace(/`([^`]+)`/g, `${ansi.code}\`$1\`${ansi.reset}`)
-    .replace(/\*\*([^*]+)\*\*/g, `${ansi.heading}$1${ansi.reset}`);
-}
-
-function parseTableRow(line: string): string[] {
-  const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
-  return trimmed.split("|").map((cell) => cell.trim());
-}
 
-function isTableSeparatorRow(cells: string[]): boolean {
-  return cells.length > 0 && cells.every((c) => /^:?-{3,}:?$/.test(c));
+  process.once("exit", cleanup);
+  const exitApp = (code: number): never => {
+    cleanup();
+    process.exit(code);
+  };
+  process.once("SIGINT", () => exitApp(130));
+  process.once("SIGTERM", () => exitApp(143));
+  return exitApp;
 }
 
-function renderTable(rows: string[][], ansi: Record<string, string>): string[] {
-  const normalized = rows.map((r) => [...r]);
-  const colCount = Math.max(...normalized.map((r) => r.length));
-  for (const row of normalized) {
-    while (row.length < colCount) row.push("");
+function subscribeEventListeners(options: AppCliOptions, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): void {
+  if (process.env.AGENT_EVENT_STDERR === "1") {
+    ctx.events.subscribe(createConsoleAgentEventListener());
   }
 
-  const widths = Array.from({ length: colCount }, (_, i) =>
-    Math.max(...normalized.map((r) => (r[i] ?? "").length)),
-  );
-
-  const line = `+${widths.map((w) => "-".repeat(w + 2)).join("+")}+`;
-  const out: string[] = [`${ansi.hr}${line}${ansi.reset}`];
-
-  normalized.forEach((row, idx) => {
-    const body = row
-      .map((cell, i) => ` ${(cell ?? "").padEnd(widths[i] ?? 0)} `)
-      .join("|");
-    const styledBody =
-      idx === 0
-        ? `${ansi.heading}|${styleInlineMarkdown(body, ansi)}|${ansi.reset}`
-        : `|${styleInlineMarkdown(body, ansi)}|`;
-    out.push(styledBody);
-    if (idx === 0) out.push(`${ansi.hr}${line}${ansi.reset}`);
-  });
-
-  out.push(`${ansi.hr}${line}${ansi.reset}`);
-  return out;
-}
-
-function formatMarkdownForTerminal(
-  markdown: string,
-  options: { useColor: boolean } = { useColor: true },
-): string {
-  const ansi = createAnsi(options.useColor);
-  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
-  const out: string[] = [];
-  let inCodeBlock = false;
-  let codeFenceLang = "";
-  let codeBoxWidth = 0;
-
-  for (let i = 0; i < lines.length; i += 1) {
-    const rawLine = lines[i];
-    const line = rawLine ?? "";
-
-    if (line.trim().startsWith("```")) {
-      if (!inCodeBlock) {
-        inCodeBlock = true;
-        codeFenceLang = line.trim().slice(3).trim();
-        const title = codeFenceLang ? ` code:${codeFenceLang} ` : " code ";
-        codeBoxWidth = Math.max(16, title.length + 4);
-        out.push(`${ansi.hr}┌${"─".repeat(codeBoxWidth)}┐${ansi.reset}`);
-        out.push(`${ansi.hr}│${ansi.reset}${ansi.dim}${title.padEnd(codeBoxWidth)}${ansi.reset}${ansi.hr}│${ansi.reset}`);
-      } else {
-        inCodeBlock = false;
-        codeFenceLang = "";
-        out.push(`${ansi.hr}└${"─".repeat(codeBoxWidth)}┘${ansi.reset}`);
-      }
-      continue;
-    }
-
-    if (inCodeBlock) {
-      const content = line.length > codeBoxWidth ? line.slice(0, codeBoxWidth) : line.padEnd(codeBoxWidth);
-      out.push(`${ansi.hr}│${ansi.reset}${ansi.code}${content}${ansi.reset}${ansi.hr}│${ansi.reset}`);
-      continue;
-    }
-
-    // Markdown table: header row + separator row + data rows
-    if (
-      line.includes("|") &&
-      i + 1 < lines.length &&
-      (lines[i + 1] ?? "").includes("|")
-    ) {
-      const header = parseTableRow(line);
-      const sep = parseTableRow(lines[i + 1] ?? "");
-      if (header.length > 1 && header.length === sep.length && isTableSeparatorRow(sep)) {
-        const rows: string[][] = [header];
-        let j = i + 2;
-        while (j < lines.length && (lines[j] ?? "").includes("|")) {
-          rows.push(parseTableRow(lines[j] ?? ""));
-          j += 1;
-        }
-        out.push(...renderTable(rows, ansi));
-        i = j - 1;
-        continue;
-      }
-    }
-
-    if (/^\s*#{1,6}\s+/.test(line)) {
-      const headingText = line.replace(/^\s*#{1,6}\s+/, "").trim();
-      out.push(`${ansi.heading}${headingText}${ansi.reset}`);
-      continue;
-    }
-
-    if (/^\s*>\s?/.test(line)) {
-      out.push(`${ansi.quote}${line}${ansi.reset}`);
-      continue;
-    }
-
-    if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
-      out.push(`${ansi.bullet}${styleInlineMarkdown(line, ansi)}${ansi.reset}`);
-      continue;
-    }
-
-    if (/^\s*---+\s*$/.test(line)) {
-      out.push(`${ansi.hr}${"─".repeat(56)}${ansi.reset}`);
-      continue;
-    }
-
-    out.push(styleInlineMarkdown(line, ansi));
+  const listeners = Array.isArray(options.eventListener)
+    ? options.eventListener
+    : options.eventListener
+      ? [options.eventListener]
+      : [];
+  for (const listener of listeners) {
+    ctx.events.subscribe(listener);
   }
-
-  return out.join("\n");
-}
-
-const markdownRenderers = new Map<"color" | "plain", MarkdownIt>();
-
-function getMarkdownRenderer(useColor: boolean): MarkdownIt {
-  const key = useColor ? "color" : "plain";
-  const cached = markdownRenderers.get(key);
-  if (cached) return cached;
-
-  const md = new MarkdownIt({
-    html: false,
-    linkify: true,
-    typographer: true,
-    breaks: false,
-  });
-  md.use(markdownItTerminal, {
-    indent: "",
-    ...(useColor
-      ? {}
-      : {
-          styleOptions: {
-            code: (s: string) => s,
-            blockquote: (s: string) => s,
-            html: (s: string) => s,
-            heading: (s: string) => s,
-            firstHeading: (s: string) => s,
-            hr: (s: string) => s,
-            listitem: (s: string) => s,
-            table: (s: string) => s,
-            paragraph: (s: string) => s,
-            strong: (s: string) => s,
-            em: (s: string) => s,
-            codespan: (s: string) => s,
-            del: (s: string) => s,
-            link: (s: string) => s,
-            href: (s: string) => s,
-          },
-        }),
-  });
-
-  markdownRenderers.set(key, md);
-  return md;
 }
 
-function normalizeAssistantMarkdown(text: string): string {
-  const source = text.replace(/\r\n/g, "\n");
-  const hasMarkdownHeadings = /^\s*#{1,6}\s+/m.test(source);
-  const sanitizeLine = (line: string): string => {
-    let next = line;
-    const trimmed = next.trim();
-    // Remove stray inline fence markers that frequently break markdown rendering.
-    if (next.includes("```") && !trimmed.startsWith("```")) {
-      next = next.replace(/```+/g, "").replace(/\s+$/, "");
-    }
-    // Keep headings stable and readable in terminal output.
-    if (/^\s*#{3,}\s+/.test(next)) {
-      next = next.replace(/^\s*#{3,}\s+/, "## ");
-    }
-    return next;
-  };
-  const normalizeListLine = (line: string): string => {
-    if (/^(\s{2,}|\t+)([*-])\s+/.test(line)) {
-      return line.replace(/^(\s{2,}|\t+)([*-])\s+/, "- ");
-    }
-    if (/^(\s{2,}|\t+)(\d+\.)\s+/.test(line)) {
-      return line.replace(/^(\s{2,}|\t+)(\d+\.)\s+/, "$2 ");
-    }
-    return line;
-  };
-  const lines = source
-    .split("\n")
-    .map(sanitizeLine)
-    .map(normalizeListLine);
-
-  const titled = lines.map((line) => {
-    const trimmed = line.trim();
-    const bulletHeading = trimmed.match(/^[-*]\s+\*\*([^*]+)\*\*:?\s*$/);
-    if (bulletHeading?.[1]) {
-      return `### ${bulletHeading[1].trim()}`;
-    }
-    const plainBulletHeading = trimmed.match(/^[-*]\s+([^`].+):\s*$/);
-    if (plainBulletHeading?.[1] && plainBulletHeading[1].length <= 48) {
-      return `### ${plainBulletHeading[1].trim()}`;
-    }
-    if (hasMarkdownHeadings) return trimmed === "Summary (3‑8 bullets)" ? "## Summary" : line;
-    const unwrapped = trimmed.replace(/^\*\*(.+)\*\*$/, "$1").trim();
-    if (/^(Key terminal output.*|Current terminal buffer.*|Summary.*|Next steps.*)$/i.test(unwrapped)) {
-      return `## ${unwrapped}`;
-    }
-    if (/^(Key observations|Findings|Analysis|Conclusion)$/i.test(unwrapped)) {
-      return `## ${unwrapped}`;
-    }
-    return line;
-  });
-
-  // Merge accidental line breaks inside list items so markdown renders as one bullet.
-  const merged: string[] = [];
-  for (let i = 0; i < titled.length; i += 1) {
-    const current = titled[i] ?? "";
-    const next = titled[i + 1] ?? "";
-    const currentTrim = current.trim();
-    const nextTrim = next.trim();
-    const isListLine = /^([-*]|\d+\.)\s+/.test(currentTrim);
-    const nextStartsNewBlock =
-      nextTrim.length === 0 ||
-      /^([-*]|\d+\.)\s+/.test(nextTrim) ||
-      /^#{1,6}\s+/.test(nextTrim) ||
-      /^```/.test(nextTrim) ||
-      /^---+$/.test(nextTrim);
-    const looksLikeWrappedContinuation =
-      isListLine &&
-      !nextStartsNewBlock &&
-      /^[0-9./~]/.test(nextTrim);
-
-    if (looksLikeWrappedContinuation) {
-      merged.push(`${current.replace(/\s+$/, "")} ${nextTrim}`);
-      i += 1;
-      continue;
-    }
-    merged.push(current);
+async function runOnReady(options: AppCliOptions, appName: string, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): Promise<void> {
+  if (!options.onReady) return;
+  try {
+    await options.onReady(ctx);
+  } catch (err) {
+    console.error(`${appName}: onReady hook failed:`, err instanceof Error ? err.message : err);
   }
+}
 
-  const out: string[] = [];
-  for (let i = 0; i < merged.length; i += 1) {
-    const line = merged[i] ?? "";
-    out.push(line);
-
-    const heading = line.trim();
-    const isOutputHeading = /^##\s*(Key terminal output|Current terminal buffer|Terminal output)/i.test(heading);
-    if (!isOutputHeading) continue;
-    if ((merged[i + 1] ?? "").trim().startsWith("```")) continue;
-
-    let j = i + 1;
-    const block: string[] = [];
-    while (j < merged.length) {
-      const current = merged[j] ?? "";
-      if (!current.trim()) {
-        if (block.length === 0) {
-          j += 1;
-          continue;
-        }
-        break;
-      }
-      if (!/^\s{2,}\S/.test(current)) break;
-      block.push(current.replace(/^\s+/, ""));
-      j += 1;
-    }
+async function createContextWithLoading(options: AppCliOptions): Promise<Awaited<ReturnType<AppCliOptions["createBotContext"]>>> {
+  const loadingText = options.ui?.loadingText ?? `${options.appName}: loading config, LLM, memory, tools...`;
+  const useLoadingSpinner = options.ui?.loadingSpinner ?? false;
+  let stopLoadingSpinner: (() => void) | null = null;
 
-    if (block.length >= 2) {
-      out.push("```text");
-      out.push(...block);
-      out.push("```");
-      i = j - 1;
+  if (loadingText !== false) {
+    if (useLoadingSpinner && Boolean(process.stderr.isTTY)) {
+      stopLoadingSpinner = startLoadingSpinner(loadingText);
+    } else {
+      console.error(loadingText);
     }
   }
 
-  const fencedCount = out.reduce((count, line) => count + (/^\s*```/.test(line) ? 1 : 0), 0);
-  if (fencedCount % 2 === 1) {
-    out.push("```");
-  }
-
-  return out.join("\n");
+  const ctx = await options.createBotContext();
+  stopLoadingSpinner?.();
+  return ctx;
 }
 
-function renderForTerminal(
-  text: string,
-  options: { renderMarkdown: boolean; useColor: boolean },
-): string {
-  if (!options.renderMarkdown) return text;
-  const normalizedText = normalizeAssistantMarkdown(text);
-  try {
-    return getMarkdownRenderer(options.useColor).render(normalizedText, {});
-  } catch {
-    return formatMarkdownForTerminal(normalizedText, { useColor: options.useColor });
+function printReady(options: AppCliOptions, kind: AgentKind): void {
+  const agentLabel = kind === REACT ? "ReAct (LangChain)" : "Deep (DeepAgents)";
+  const readyText = options.ui?.readyText ?? `Ready. Agent: ${agentLabel}`;
+  if (readyText !== false) {
+    console.error(readyText);
   }
 }
 
-function startLoadingSpinner(message: string): () => void {
-  const frames = ["", ".", "..", "..."];
-  let frameIndex = 0;
-  let lastLength = 0;
-  const render = () => {
-    const frame = frames[frameIndex % frames.length] ?? "";
-    const trimmed = message.trim();
-    const base = trimmed.startsWith("⏳") ? trimmed : `⏳ ${trimmed}`;
-    const line = `${base}${frame}`;
-    const padded = lastLength > line.length ? line.padEnd(lastLength, " ") : line;
-    process.stderr.write(`\r${padded}\r`);
-    lastLength = padded.length;
-    frameIndex += 1;
-  };
-  render();
-  const timer = setInterval(render, 90);
-  return () => {
-    clearInterval(timer);
-    process.stderr.write(`\r${" ".repeat(lastLength)}\r`);
-  };
+function resolveAgentKind(parsed: ReturnType<typeof parseArgs>, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): AgentKind {
+  if (parsed.explicitKind) return parsed.kind;
+  return readDefaultAgentKindFromConfig(ctx) ?? parsed.kind;
 }
 
-async function interactive(
-  ctx: BotContext,
-  kind: AgentKind,
+async function runSingleQuery(
   options: AppCliOptions,
-  exitApp: (code: number) => never
-) {
-  const name = kind === REACT ? "ReAct" : "Deep";
-  const runtime = await createRuntime(ctx, kind);
-  const userInfo = os.userInfo();
-  const userLabel = options.ui?.userLabel ?? `${userInfo.username}`;
-  const assistantLabel = options.ui?.assistantLabel ?? name;
+  ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>,
+  kind: AgentKind,
+  query: string,
+): Promise<void> {
+  const text = await runOne(ctx, kind, query);
   const useColor = options.ui?.useColor ?? (Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
   const renderMarkdown = options.ui?.renderMarkdown ?? true;
-  const echoUserQuestion = options.ui?.echoUserQuestion ?? true;
-  const showProcessingSpinner =
-    options.ui?.processingSpinner ?? Boolean(process.stderr.isTTY);
-  const processingText = options.ui?.processingText ?? "Processing";
-
-  const color = {
-    reset: useColor ? "\x1b[0m" : "",
-    dim: useColor ? "\x1b[2m" : "",
-    user: useColor ? "\x1b[38;5;39m" : "",
-    bot: useColor ? "\x1b[38;5;48m" : "",
-    prompt: useColor ? "\x1b[38;5;245m" : "",
-    promptUser: useColor ? "\x1b[1;38;5;45m" : "",
-  };
-  const hr = `${color.dim}${"-".repeat(56)}${color.reset}`;
-  const promptText = `${color.prompt}[${color.promptUser}${userLabel}${color.reset}${color.prompt}]${color.reset} `;
-
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const userLabelPrefixPattern = new RegExp(`^(?:\\[${escapeRegExp(userLabel)}\\]\\s*)+`, "i");
-  const prompt = () =>
-    rl.question(promptText, async (line) => {
-      const qRaw = line?.trim();
-      const q = qRaw?.replace(userLabelPrefixPattern, "").trim();
-      if (!q) {
-        prompt();
-        return;
-      }
-      if (q === "exit" || q === "quit") {
-        rl.close();
-        exitApp(0);
-      }
-
-      const handler = options.interactiveCommands?.[q.toLowerCase()];
-      if (handler) {
-        await handler(ctx);
-        prompt();
-        return;
-      }
-
-      let stopProcessingSpinner: (() => void) | null = null;
-      try {
-        console.log(`\n${hr}`);
-        if (echoUserQuestion) {
-          console.log(`${color.user}[${userLabel}]${color.reset}`);
-          console.log(`> ${q}`);
-          console.log("");
-        }
-        console.log(`${color.bot}[${assistantLabel}]${color.reset}`);
-        stopProcessingSpinner = showProcessingSpinner
-          ? startLoadingSpinner(processingText === false ? "⏳" : `⏳ ${processingText}`)
-          : null;
-        const { text } = await runtime.run(q);
-        if (stopProcessingSpinner) {
-          stopProcessingSpinner();
-          stopProcessingSpinner = null;
-        }
-        console.log(renderForTerminal(text, { renderMarkdown, useColor }));
-        console.log(`${hr}\n`);
-      } catch (err) {
-        if (stopProcessingSpinner) {
-          stopProcessingSpinner();
-          stopProcessingSpinner = null;
-        }
-        console.error("Error:", err instanceof Error ? err.message : err);
-      } finally {
-        if (stopProcessingSpinner) {
-          stopProcessingSpinner();
-          stopProcessingSpinner = null;
-        }
-      }
-      prompt();
-    });
-  const introText =
-    options.ui?.interactiveIntro ??
-    `${options.appName} (${name} agent). Type your message or "exit" to quit.`;
-  if (introText !== false) {
-    console.log(`${introText}\n`);
-  }
-  prompt();
-}
-
-export function createStructuredRunEventListener(
-  writer: (line: string) => void = console.error
-): AgentEventListener {
-  let step = 0;
-  let lastCommandSignature = "";
-  const stepActionByNumber = new Map<number, string>();
-  const okMark = process.stderr.isTTY && !process.env.NO_COLOR ? "\x1b[32m✔\x1b[0m" : "✔";
-
-  const asRecord = (value: unknown): Record<string, unknown> | null =>
-    typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
-
-  const asNumber = (value: unknown): number | null =>
-    typeof value === "number" && Number.isFinite(value) ? value : null;
-
-  const asString = (value: unknown): string | null =>
-    typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-  const asAnyString = (value: unknown): string | null =>
-    typeof value === "string" ? value : null;
-
-  const parseJsonObject = (value: unknown): Record<string, unknown> | null => {
-    if (typeof value !== "string") return null;
-    try {
-      const parsed = JSON.parse(value) as unknown;
-      return asRecord(parsed);
-    } catch {
-      return null;
-    }
-  };
-
-  const extractCommandMeta = (args: unknown) => {
-    const rec = asRecord(args) ?? parseJsonObject(args);
-    if (!rec) return null;
-    const commandRaw = asAnyString(rec.command);
-    if (commandRaw === null) return null;
-    const command = commandRaw.trim();
-    return {
-      command,
-      windowId: asNumber(rec.windowId),
-      tabIndex: asNumber(rec.tabIndex),
-      sessionId: asString(rec.sessionId),
-    };
-  };
-
-  const isNoopCaptureCommand = (command: string): boolean => {
-    const normalized = command.trim().replace(/\s+/g, " ");
-    return (
-      normalized === "" ||
-      normalized === ":" ||
-      normalized === "true" ||
-      normalized === "printf ''" ||
-      normalized === "printf \"\""
-    );
-  };
-
-  const extractToolResultMeta = (payload: unknown) => {
-    const payloadRec = asRecord(payload);
-    const rawResult = payloadRec ? (payloadRec.result ?? null) : null;
-    const resultRec = asRecord(rawResult) ?? parseJsonObject(rawResult);
-    const nestedResult = resultRec ? asRecord(resultRec.result) : null;
-    const output =
-      asString((nestedResult ?? resultRec ?? {}).output) ??
-      asString((nestedResult ?? resultRec ?? {}).result as unknown);
-    const outputLines = output ? output.split(/\r?\n/).filter((line) => line.length > 0).length : null;
-    const error = asString((nestedResult ?? resultRec ?? {}).error);
-    return { outputLines, error };
-  };
-
-  return (event: AgentEvent) => {
-    switch (event.name) {
-      case "agent.react.run.start":
-      case "agent.deep.run.start":
-        step = 0;
-        lastCommandSignature = "";
-        stepActionByNumber.clear();
-        writer("Analyzing started");
-        return;
-      case "agent.react.skill.matched": {
-        const payload = (event.payload ?? {}) as { skill?: string; score?: number };
-        const score = typeof payload.score === "number" ? payload.score.toFixed(3) : "?";
-        writer(`[skill] matched ${payload.skill ?? "unknown"} (score ${score})`);
-        return;
-      }
-      case "agent.react.tool.invoke.start": {
-        step += 1;
-        const payload = (event.payload ?? {}) as { args?: unknown };
-        const commandMeta = extractCommandMeta(payload.args);
-        if (commandMeta) {
-          const signature = `${commandMeta.command}|${commandMeta.windowId ?? ""}|${commandMeta.tabIndex ?? ""}|${commandMeta.sessionId ?? ""}`;
-          const isRepeat = signature === lastCommandSignature;
-          lastCommandSignature = signature;
-          const action = isNoopCaptureCommand(commandMeta.command)
-            ? "capture current screen"
-            : commandMeta.command;
-          stepActionByNumber.set(step, `${action}${isRepeat ? " (repeat)" : ""}`);
-        } else {
-          stepActionByNumber.set(step, `tool: ${event.to}`);
-        }
-        return;
-      }
-      case "agent.react.tool.invoke.done": {
-        const resultMeta = extractToolResultMeta(event.payload);
-        const action = stepActionByNumber.get(step) ?? `tool: ${event.to}`;
-        if (resultMeta.error) {
-          writer(`[step ${step}] ${action} ✖ (${resultMeta.error})`);
-          stepActionByNumber.delete(step);
-          return;
-        }
-        writer(`[step ${step}] ${action} ${okMark}`);
-        stepActionByNumber.delete(step);
-        return;
-      }
-      case "agent.react.tool.invoke.error": {
-        const payload = (event.payload ?? {}) as { error?: unknown };
-        const action = stepActionByNumber.get(step) ?? `tool: ${event.to}`;
-        const message =
-          typeof payload.error === "string"
-            ? payload.error
-            : payload.error instanceof Error
-              ? payload.error.message
-              : "unknown error";
-        writer(`[step ${step}] ${action} ✖ (${message})`);
-        stepActionByNumber.delete(step);
-        return;
-      }
-      case "agent.react.run.done":
-      case "agent.deep.run.done":
-        writer("completed");
-        return;
-      default:
-        return;
-    }
-  };
+  console.log(renderForTerminal(text, { renderMarkdown, useColor }));
 }
 
 export function runAppCli(options: AppCliOptions): void {
-  const { appName, createBotContext } = options;
-
-  async function main() {
-    const { kind, query } = parseArgs();
-    const agentLabel = kind === REACT ? "ReAct (LangChain)" : "Deep (DeepAgents)";
-    const loadingText =
-      options.ui?.loadingText ?? `${appName}: loading config, LLM, memory, tools...`;
-    const useLoadingSpinner = options.ui?.loadingSpinner ?? false;
-    let stopLoadingSpinner: (() => void) | null = null;
-    if (loadingText !== false) {
-      if (useLoadingSpinner && Boolean(process.stderr.isTTY)) {
-        stopLoadingSpinner = startLoadingSpinner(loadingText);
-      } else {
-        console.error(loadingText);
-      }
-    }
-    const ctx = await createBotContext();
-    if (stopLoadingSpinner) {
-      stopLoadingSpinner();
-    }
-    let didCleanup = false;
-    const cleanup = () => {
-      if (didCleanup) return;
-      didCleanup = true;
-      try {
-        options.onShutdown?.(ctx);
-      } catch (err) {
-        console.error(
-          `${appName}: onShutdown hook failed:`,
-          err instanceof Error ? err.message : err,
-        );
-      }
-    };
-    const exitApp = (code: number): never => {
-      cleanup();
-      process.exit(code);
-    };
-    process.once("exit", cleanup);
-    process.once("SIGINT", () => exitApp(130));
-    process.once("SIGTERM", () => exitApp(143));
+  const main = async () => {
+    const parsed = parseArgs();
+    const ctx = await createContextWithLoading(options);
+    const kind = resolveAgentKind(parsed, ctx);
+    const exitApp = createExitHandler(options.appName, options.onShutdown, ctx);
 
-    if (process.env.AGENT_EVENT_STDERR === "1") {
-      ctx.events.subscribe(createConsoleAgentEventListener());
-    }
-    const eventListeners = Array.isArray(options.eventListener)
-      ? options.eventListener
-      : options.eventListener
-        ? [options.eventListener]
-        : [];
-    for (const listener of eventListeners) {
-      ctx.events.subscribe(listener);
-    }
-    if (options.onReady) {
-      try {
-        await options.onReady(ctx);
-      } catch (err) {
-        console.error(
-          `${appName}: onReady hook failed:`,
-          err instanceof Error ? err.message : err,
-        );
-      }
-    }
-    const readyText = options.ui?.readyText ?? `Ready. Agent: ${agentLabel}`;
-    if (readyText !== false) {
-      console.error(readyText);
-    }
+    subscribeEventListeners(options, ctx);
+    await runOnReady(options, options.appName, ctx);
+    printReady(options, kind);
 
-    if (query) {
-      const text = await runOne(ctx, kind, query);
-      const useColor = options.ui?.useColor ?? (Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
-      const renderMarkdown = options.ui?.renderMarkdown ?? true;
-      console.log(renderForTerminal(text, { renderMarkdown, useColor }));
-      cleanup();
-      return;
+    if (parsed.query) {
+      await runSingleQuery(options, ctx, kind, parsed.query);
+      exitApp(0);
     }
 
     await interactive(ctx, kind, options, exitApp);
-  }
+  };
 
   main().catch((err) => {
     console.error(err);