@easynet/agent-runtime 1.0.3 → 1.0.4

package/agent-runtime/src/cli/event-listener.ts

@@ -0,0 +1,162 @@
+import type { AgentEvent, AgentEventListener } from "@easynet/agent-common";
+
+interface CommandMeta {
+  command: string;
+  windowId: number | null;
+  tabIndex: number | null;
+  sessionId: string | null;
+}
+
+interface ToolResultMeta {
+  outputLines: number | null;
+  error: string | null;
+}
+
+interface ListenerState {
+  step: number;
+  lastCommandSignature: string;
+  stepActionByNumber: Map<number, string>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function asTrimmedString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function parseJsonObject(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "string") return null;
+  try {
+    return asRecord(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+
+function extractCommandMeta(args: unknown): CommandMeta | null {
+  const rec = asRecord(args) ?? parseJsonObject(args);
+  if (!rec) return null;
+  const commandRaw = asString(rec.command);
+  if (commandRaw === null) return null;
+  return {
+    command: commandRaw.trim(),
+    windowId: asNumber(rec.windowId),
+    tabIndex: asNumber(rec.tabIndex),
+    sessionId: asTrimmedString(rec.sessionId),
+  };
+}
+
+function isNoopCaptureCommand(command: string): boolean {
+  const normalized = command.trim().replace(/\s+/g, " ");
+  return normalized === "" || normalized === ":" || normalized === "true" || normalized === "printf ''" || normalized === 'printf ""';
+}
+
+function extractToolResultMeta(payload: unknown): ToolResultMeta {
+  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 = asTrimmedString((nestedResult ?? resultRec ?? {}).output)
+    ?? asTrimmedString((nestedResult ?? resultRec ?? {}).result as unknown);
+  const error = asTrimmedString((nestedResult ?? resultRec ?? {}).error);
+  return {
+    outputLines: output ? output.split(/\r?\n/).filter((line) => line.length > 0).length : null,
+    error,
+  };
+}
+
+function recordToolStart(state: ListenerState, event: AgentEvent): void {
+  state.step += 1;
+  const payload = (event.payload ?? {}) as { args?: unknown };
+  const commandMeta = extractCommandMeta(payload.args);
+
+  if (!commandMeta) {
+    state.stepActionByNumber.set(state.step, `tool: ${event.to}`);
+    return;
+  }
+
+  const signature = `${commandMeta.command}|${commandMeta.windowId ?? ""}|${commandMeta.tabIndex ?? ""}|${commandMeta.sessionId ?? ""}`;
+  const isRepeat = signature === state.lastCommandSignature;
+  state.lastCommandSignature = signature;
+  const action = isNoopCaptureCommand(commandMeta.command) ? "capture current screen" : commandMeta.command;
+  state.stepActionByNumber.set(state.step, `${action}${isRepeat ? " (repeat)" : ""}`);
+}
+
+function writeToolDone(state: ListenerState, event: AgentEvent, writer: (line: string) => void, okMark: string): void {
+  const resultMeta = extractToolResultMeta(event.payload);
+  const action = state.stepActionByNumber.get(state.step) ?? `tool: ${event.to}`;
+
+  if (resultMeta.error) {
+    writer(`[step ${state.step}] ${action} ✖ (${resultMeta.error})`);
+    state.stepActionByNumber.delete(state.step);
+    return;
+  }
+
+  writer(`[step ${state.step}] ${action} ${okMark}`);
+  state.stepActionByNumber.delete(state.step);
+}
+
+function writeToolError(state: ListenerState, event: AgentEvent, writer: (line: string) => void): void {
+  const payload = (event.payload ?? {}) as { error?: unknown };
+  const action = state.stepActionByNumber.get(state.step) ?? `tool: ${event.to}`;
+  const message = typeof payload.error === "string"
+    ? payload.error
+    : payload.error instanceof Error
+      ? payload.error.message
+      : "unknown error";
+  writer(`[step ${state.step}] ${action} ✖ (${message})`);
+  state.stepActionByNumber.delete(state.step);
+}
+
+function handleEvent(state: ListenerState, event: AgentEvent, writer: (line: string) => void, okMark: string): void {
+  switch (event.name) {
+    case "agent.react.run.start":
+    case "agent.deep.run.start":
+      state.step = 0;
+      state.lastCommandSignature = "";
+      state.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":
+      recordToolStart(state, event);
+      return;
+    case "agent.react.tool.invoke.done":
+      writeToolDone(state, event, writer, okMark);
+      return;
+    case "agent.react.tool.invoke.error":
+      writeToolError(state, event, writer);
+      return;
+    case "agent.react.run.done":
+    case "agent.deep.run.done":
+      writer("completed");
+      return;
+    default:
+      return;
+  }
+}
+
+export function createStructuredRunEventListener(writer: (line: string) => void = console.error): AgentEventListener {
+  const state: ListenerState = {
+    step: 0,
+    lastCommandSignature: "",
+    stepActionByNumber: new Map<number, string>(),
+  };
+  const okMark = process.stderr.isTTY && !process.env.NO_COLOR ? "\x1b[32m✔\x1b[0m" : "✔";
+  return (event: AgentEvent) => handleEvent(state, event, writer, okMark);
+}

package/agent-runtime/src/cli/interactive.ts

@@ -0,0 +1,144 @@
+import os from "node:os";
+import { createInterface } from "node:readline";
+import type { BotContext } from "../core/context.js";
+import { createRuntime } from "./runtime.js";
+import { startLoadingSpinner } from "./spinner.js";
+import { renderForTerminal } from "./terminal-render.js";
+import { DEEP, REACT, type AgentKind, type AppCliOptions, type InteractiveCommandHandler } from "./types.js";
+
+const builtinInteractiveCommands: Record<string, InteractiveCommandHandler> = {
+  "list tools": (ctx) => {
+    const tools = (ctx.tools as Array<{ name?: unknown; description?: unknown }>)
+      .map((tool) => ({
+        name: typeof tool.name === "string" ? tool.name : "(unnamed-tool)",
+        description:
+          typeof tool.description === "string" && tool.description.trim().length > 0
+            ? tool.description.trim()
+            : "No description",
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    console.log(`Available tools (${tools.length}):`);
+    for (const tool of tools) {
+      console.log(`- ${tool.name}: ${tool.description}`);
+    }
+  },
+  "list skills": (ctx) => {
+    const skills = (ctx.skillSet?.list() ?? [])
+      .map((skill) => ({ name: skill.name, description: (skill.description ?? "").trim() || "No description" }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    console.log(`Available skills (${skills.length}):`);
+    for (const skill of skills) {
+      console.log(`- ${skill.name}: ${skill.description}`);
+    }
+  },
+};
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function createCliColors(useColor: boolean) {
+  return {
+    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" : "",
+  };
+}
+
+function resolveUiOptions(kind: AgentKind, options: AppCliOptions) {
+  const userLabel = options.ui?.userLabel ?? os.userInfo().username;
+  const assistantLabel = options.ui?.assistantLabel ?? (kind === REACT ? "ReAct" : "Deep");
+  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";
+  return { userLabel, assistantLabel, useColor, renderMarkdown, echoUserQuestion, showProcessingSpinner, processingText };
+}
+
+async function runInteractiveCommand(
+  ctx: BotContext,
+  input: string,
+  commands: Record<string, InteractiveCommandHandler> | undefined,
+): Promise<boolean> {
+  const key = input.toLowerCase();
+  const handler = commands?.[key] ?? builtinInteractiveCommands[key];
+  if (!handler) return false;
+  await handler(ctx);
+  return true;
+}
+
+async function runUserQuery(
+  query: string,
+  runtime: { run: (userMessage: string) => Promise<{ text: string }> },
+  ui: ReturnType<typeof resolveUiOptions>,
+  visuals: { hr: string; userPrefix: string; assistantPrefix: string },
+): Promise<void> {
+  let stopProcessingSpinner: (() => void) | null = null;
+  try {
+    console.log(`\n${visuals.hr}`);
+    if (ui.echoUserQuestion) {
+      console.log(visuals.userPrefix);
+      console.log(`> ${query}`);
+      console.log("");
+    }
+    console.log(visuals.assistantPrefix);
+    stopProcessingSpinner = ui.showProcessingSpinner
+      ? startLoadingSpinner(ui.processingText === false ? "⏳" : `⏳ ${ui.processingText}`)
+      : null;
+
+    const { text } = await runtime.run(query);
+    stopProcessingSpinner?.();
+    stopProcessingSpinner = null;
+
+    console.log(renderForTerminal(text, { renderMarkdown: ui.renderMarkdown, useColor: ui.useColor }));
+    console.log(`${visuals.hr}\n`);
+  } catch (err) {
+    stopProcessingSpinner?.();
+    console.error("Error:", err instanceof Error ? err.message : err);
+  }
+}
+
+export async function interactive(
+  ctx: BotContext,
+  kind: AgentKind,
+  options: AppCliOptions,
+  exitApp: (code: number) => never,
+): Promise<void> {
+  const runtime = await createRuntime(ctx, kind);
+  const ui = resolveUiOptions(kind, options);
+  const color = createCliColors(ui.useColor);
+  const hr = `${color.dim}${"-".repeat(56)}${color.reset}`;
+  const promptText = `${color.prompt}[${color.promptUser}${ui.userLabel}${color.reset}${color.prompt}]${color.reset} `;
+  const userPrefix = `${color.user}[${ui.userLabel}]${color.reset}`;
+  const assistantPrefix = `${color.bot}[${ui.assistantLabel}]${color.reset}`;
+  const userLabelPrefixPattern = new RegExp(`^(?:\\[${escapeRegExp(ui.userLabel)}\\]\\s*)+`, "i");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const introText = options.ui?.interactiveIntro ?? `${options.appName} (${kind === DEEP ? "Deep" : "ReAct"} agent). Type your message or "exit" to quit.`;
+  if (introText !== false) console.log(`${introText}\n`);
+
+  const prompt = () => {
+    rl.question(promptText, async (line) => {
+      const query = line?.trim()?.replace(userLabelPrefixPattern, "").trim();
+      if (!query) return prompt();
+      if (query === "exit" || query === "quit") {
+        rl.close();
+        exitApp(0);
+      }
+
+      const handled = await runInteractiveCommand(ctx, query, options.interactiveCommands);
+      if (handled) return prompt();
+
+      await runUserQuery(query, runtime, ui, { hr, userPrefix, assistantPrefix });
+      prompt();
+    });
+  };
+
+  prompt();
+}

package/agent-runtime/src/cli/runtime.ts

@@ -0,0 +1,31 @@
+import { createReactAgent, type ReactAgentRuntime } from "../agents/react-agent.js";
+import { createDeepAgent, type DeepAgentRuntime } from "../agents/deep-agent.js";
+import { malformedToolCallMiddleware } from "../middleware/malformed-tool-call-middleware.js";
+import type { BotContext } from "../core/context.js";
+import { DEEP, REACT, type AgentKind } from "./types.js";
+
+export function readDefaultAgentKindFromConfig(ctx: BotContext): AgentKind | undefined {
+  const defaultAgent = (ctx.config?.app as { defaultAgent?: unknown } | undefined)?.defaultAgent;
+  if (typeof defaultAgent !== "string") return undefined;
+  const value = defaultAgent.trim().toLowerCase();
+  if (value === REACT || value === DEEP) return value;
+  return undefined;
+}
+
+export async function createRuntime(
+  ctx: BotContext,
+  kind: AgentKind,
+): Promise<ReactAgentRuntime | DeepAgentRuntime> {
+  if (kind === REACT) {
+    return createReactAgent(ctx, {
+      middleware: [malformedToolCallMiddleware()],
+    });
+  }
+  return createDeepAgent(ctx);
+}
+
+export 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;
+}

package/agent-runtime/src/cli/spinner.ts

@@ -0,0 +1,23 @@
+export 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`);
+  };
+}

package/agent-runtime/src/cli/terminal-render.ts

@@ -0,0 +1,322 @@
+import MarkdownIt from "markdown-it";
+import markdownItTerminal from "markdown-it-terminal";
+
+interface RenderOptions {
+  renderMarkdown: boolean;
+  useColor: boolean;
+}
+
+interface FallbackRenderOptions {
+  useColor: boolean;
+}
+
+type AnsiColors = Record<string, string>;
+
+const markdownRenderers = new Map<"color" | "plain", MarkdownIt>();
+
+function createAnsi(useColor: boolean): AnsiColors {
+  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: AnsiColors): 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: AnsiColors): string[] {
+  const normalized = rows.map((row) => [...row]);
+  const colCount = Math.max(...normalized.map((row) => row.length));
+  for (const row of normalized) {
+    while (row.length < colCount) row.push("");
+  }
+
+  const widths = Array.from({ length: colCount }, (_, i) =>
+    Math.max(...normalized.map((row) => (row[i] ?? "").length)),
+  );
+  const border = `+${widths.map((w) => "-".repeat(w + 2)).join("+")}+`;
+  const output: string[] = [`${ansi.hr}${border}${ansi.reset}`];
+
+  normalized.forEach((row, idx) => {
+    const body = row.map((cell, i) => ` ${(cell ?? "").padEnd(widths[i] ?? 0)} `).join("|");
+    const styled = idx === 0
+      ? `${ansi.heading}|${styleInlineMarkdown(body, ansi)}|${ansi.reset}`
+      : `|${styleInlineMarkdown(body, ansi)}|`;
+    output.push(styled);
+    if (idx === 0) output.push(`${ansi.hr}${border}${ansi.reset}`);
+  });
+
+  output.push(`${ansi.hr}${border}${ansi.reset}`);
+  return output;
+}
+
+function appendCodeFenceLine(line: string, state: { inCodeBlock: boolean; codeBoxWidth: number; }, ansi: AnsiColors, out: string[]): void {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("```")) return;
+
+  if (!state.inCodeBlock) {
+    const lang = trimmed.slice(3).trim();
+    const title = lang ? ` code:${lang} ` : " code ";
+    state.codeBoxWidth = Math.max(16, title.length + 4);
+    state.inCodeBlock = true;
+    out.push(`${ansi.hr}┌${"─".repeat(state.codeBoxWidth)}┐${ansi.reset}`);
+    out.push(`${ansi.hr}│${ansi.reset}${ansi.dim}${title.padEnd(state.codeBoxWidth)}${ansi.reset}${ansi.hr}│${ansi.reset}`);
+    return;
+  }
+
+  state.inCodeBlock = false;
+  out.push(`${ansi.hr}└${"─".repeat(state.codeBoxWidth)}┘${ansi.reset}`);
+}
+
+function renderMarkdownTable(lines: string[], index: number, ansi: AnsiColors): { nextIndex: number; rendered: string[] } | null {
+  const line = lines[index] ?? "";
+  const next = lines[index + 1] ?? "";
+  if (!line.includes("|") || !next.includes("|")) return null;
+
+  const header = parseTableRow(line);
+  const separator = parseTableRow(next);
+  if (!(header.length > 1 && header.length === separator.length && isTableSeparatorRow(separator))) {
+    return null;
+  }
+
+  const rows: string[][] = [header];
+  let cursor = index + 2;
+  while (cursor < lines.length && (lines[cursor] ?? "").includes("|")) {
+    rows.push(parseTableRow(lines[cursor] ?? ""));
+    cursor += 1;
+  }
+
+  return { nextIndex: cursor - 1, rendered: renderTable(rows, ansi) };
+}
+
+function formatMarkdownForTerminal(markdown: string, options: FallbackRenderOptions = { useColor: true }): string {
+  const ansi = createAnsi(options.useColor);
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  const out: string[] = [];
+  const state = { inCodeBlock: false, codeBoxWidth: 0 };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    const before = state.inCodeBlock;
+    appendCodeFenceLine(line, state, ansi, out);
+    if (line.trim().startsWith("```")) continue;
+
+    if (before && state.inCodeBlock) {
+      const content = line.length > state.codeBoxWidth ? line.slice(0, state.codeBoxWidth) : line.padEnd(state.codeBoxWidth);
+      out.push(`${ansi.hr}│${ansi.reset}${ansi.code}${content}${ansi.reset}${ansi.hr}│${ansi.reset}`);
+      continue;
+    }
+
+    const table = renderMarkdownTable(lines, i, ansi);
+    if (table) {
+      out.push(...table.rendered);
+      i = table.nextIndex;
+      continue;
+    }
+
+    if (/^\s*#{1,6}\s+/.test(line)) {
+      out.push(`${ansi.heading}${line.replace(/^\s*#{1,6}\s+/, "").trim()}${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");
+}
+
+function sanitizeLine(line: string): string {
+  let next = line;
+  const trimmed = next.trim();
+  if (next.includes("```") && !trimmed.startsWith("```")) {
+    next = next.replace(/```+/g, "").replace(/\s+$/, "");
+  }
+  if (/^\s*#{3,}\s+/.test(next)) {
+    next = next.replace(/^\s*#{3,}\s+/, "## ");
+  }
+  return next;
+}
+
+function 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;
+}
+
+function applyHeadingHeuristics(lines: string[], hasMarkdownHeadings: boolean): string[] {
+  return lines.map((line) => {
+    const trimmed = line.trim();
+    const bulletHeading = trimmed.match(/^[-*]\s+\*\*([^*]+)\*\*: ?\s*$/);
+    if (bulletHeading?.[1]) return `### ${bulletHeading[1].trim()}`;
+
+    const plainBullet = trimmed.match(/^[-*]\s+([^`].+):\s*$/);
+    if (plainBullet?.[1] && plainBullet[1].length <= 48) {
+      return `### ${plainBullet[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;
+  });
+}
+
+function mergeWrappedListItems(lines: string[]): string[] {
+  const merged: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const current = lines[i] ?? "";
+    const next = lines[i + 1] ?? "";
+    const isListLine = /^([-*]|\d+\.)\s+/.test(current.trim());
+    const nextTrim = next.trim();
+    const nextStartsNewBlock =
+      nextTrim.length === 0 ||
+      /^([-*]|\d+\.)\s+/.test(nextTrim) ||
+      /^#{1,6}\s+/.test(nextTrim) ||
+      /^```/.test(nextTrim) ||
+      /^---+$/.test(nextTrim);
+    const wrappedContinuation = isListLine && !nextStartsNewBlock && /^[0-9./~]/.test(nextTrim);
+
+    if (wrappedContinuation) {
+      merged.push(`${current.replace(/\s+$/, "")} ${nextTrim}`);
+      i += 1;
+      continue;
+    }
+    merged.push(current);
+  }
+  return merged;
+}
+
+function fenceIndentedOutputBlocks(lines: string[]): string[] {
+  const output: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    output.push(line);
+
+    const heading = line.trim();
+    const isOutputHeading = /^##\s*(Key terminal output|Current terminal buffer|Terminal output)/i.test(heading);
+    if (!isOutputHeading) continue;
+    if ((lines[i + 1] ?? "").trim().startsWith("```")) continue;
+
+    let j = i + 1;
+    const block: string[] = [];
+    while (j < lines.length) {
+      const current = lines[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) {
+      output.push("```text", ...block, "```");
+      i = j - 1;
+    }
+  }
+  return output;
+}
+
+function ensureBalancedCodeFences(lines: string[]): string[] {
+  const count = lines.reduce((acc, line) => acc + (/^\s*```/.test(line) ? 1 : 0), 0);
+  if (count % 2 === 0) return lines;
+  return [...lines, "```"];
+}
+
+function normalizeAssistantMarkdown(text: string): string {
+  const source = text.replace(/\r\n/g, "\n");
+  const hasHeadings = /^\s*#{1,6}\s+/m.test(source);
+  const sanitized = source.split("\n").map(sanitizeLine).map(normalizeListLine);
+  const titled = applyHeadingHeuristics(sanitized, hasHeadings);
+  const merged = mergeWrappedListItems(titled);
+  const fenced = fenceIndentedOutputBlocks(merged);
+  return ensureBalancedCodeFences(fenced).join("\n");
+}
+
+function getMarkdownRenderer(useColor: boolean): MarkdownIt {
+  const key = useColor ? "color" : "plain";
+  const cached = markdownRenderers.get(key);
+  if (cached) return cached;
+
+  const renderer = new MarkdownIt({ html: false, linkify: true, typographer: true, breaks: false });
+  renderer.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, renderer);
+  return renderer;
+}
+
+export function renderForTerminal(text: string, options: RenderOptions): string {
+  if (!options.renderMarkdown) return text;
+  const normalized = normalizeAssistantMarkdown(text);
+  try {
+    return getMarkdownRenderer(options.useColor).render(normalized, {});
+  } catch {
+    return formatMarkdownForTerminal(normalized, { useColor: options.useColor });
+  }
+}