@easynet/agent-runtime 1.0.1

package/src/cli.ts

@@ -0,0 +1,745 @@
+/**
+ * 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" : "",
+  };
+}
+
+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));
+}
+
+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("");
+  }
+
+  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));
+  }
+
+  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);
+  }
+
+  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;
+    }
+
+    if (block.length >= 2) {
+      out.push("```text");
+      out.push(...block);
+      out.push("```");
+      i = j - 1;
+    }
+  }
+
+  const fencedCount = out.reduce((count, line) => count + (/^\s*```/.test(line) ? 1 : 0), 0);
+  if (fencedCount % 2 === 1) {
+    out.push("```");
+  }
+
+  return out.join("\n");
+}
+
+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 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`);
+  };
+}
+
+async function interactive(
+  ctx: BotContext,
+  kind: AgentKind,
+  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;
+  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;
+    }
+  };
+}
+
+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));
+
+    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);
+    }
+
+    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;
+    }
+
+    await interactive(ctx, kind, options, exitApp);
+  }
+
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}