feat(cli): add optional server TUI log view

Author: reoring

src/cli.ts

@@ -11,6 +11,7 @@
 import type { AgentCoreConfig } from "./core/agentcore.js";
 import type { LogLevel } from "./core/observability.js";
 import { startCoreRuntime } from "./core/core-runtime.js";
+import { CoreServerTui } from "./tui/core-server-tui.js";
 import { ExecutionBudget } from "./core/execution-budget.js";
 import { BackpressureController } from "./core/backpressure.js";
 import { CircuitBreakerRegistry } from "./core/circuit-breaker.js";
@@ -29,6 +30,7 @@ import type { WorkerTask, Job } from "./types/index.js";
 interface SharedOptions {
   help: boolean;
   version: boolean;
+  tui: boolean | undefined;
   concurrency: number | undefined;
   rps: number | undefined;
   maxCost: number | undefined;
@@ -56,14 +58,17 @@ const HELP_TEXT = `
 roboppi — execution-control runtime for agentic workers
 
 USAGE
-  roboppi [options]                          Start Core IPC server mode
+  roboppi                                   Show help (interactive)
+  roboppi server [options]                   Start Core IPC server mode (default: TUI when interactive)
+  roboppi [options]                          Start Core IPC server mode (when non-interactive)
   roboppi run [options] <instructions...>    Run a one-shot worker task
   roboppi workflow <workflow.yaml> [options] Run a workflow YAML
   roboppi daemon <daemon.yaml> [options]     Run daemon mode (resident workflows)
   roboppi agent [options] <instructions...>  Alias for 'roboppi run'
 
 IPC SERVER MODE
   Reads JSON Lines from stdin, writes responses to stdout. Logs go to stderr.
+  TUI is enabled by default when stderr is a TTY; disable with --no-tui.
 
 RUN MODE OPTIONS
   --worker <kind>         Worker to use: opencode, claude-code, codex  (required)
@@ -88,6 +93,9 @@ SHARED OPTIONS
 
   --log-level <level>     Log level: debug|info|warn|error|fatal       (default: info)
 
+  --tui                   Force TUI logs UI (stderr)
+  --no-tui, --plain       Disable TUI; emit JSON logs to stderr
+
   --help, -h              Show this help message
   --version, -v           Show version
 
@@ -139,6 +147,7 @@ function parseCliArgs(argv: string[]): CliMode {
   const shared: SharedOptions = {
     help: false,
     version: false,
+    tui: undefined,
     concurrency: undefined,
     rps: undefined,
     maxCost: undefined,
@@ -224,6 +233,8 @@ function parseCliArgs(argv: string[]): CliMode {
     switch (arg) {
       case "--help": case "-h": shared.help = true; break;
       case "--version": case "-v": shared.version = true; break;
+      case "--tui": shared.tui = true; break;
+      case "--no-tui": case "--plain": shared.tui = false; break;
       case "--concurrency": shared.concurrency = nextInt(); break;
       case "--rps": shared.rps = nextInt(); break;
       case "--max-cost": shared.maxCost = nextInt(); break;
@@ -246,6 +257,21 @@ function parseCliArgs(argv: string[]): CliMode {
   return { mode: "server", opts: shared };
 }
 
+function parseEnvBool(value: string | undefined): boolean | undefined {
+  if (value === undefined) return undefined;
+  const v = value.trim().toLowerCase();
+  if (v === "1" || v === "true" || v === "yes" || v === "on") return true;
+  if (v === "0" || v === "false" || v === "no" || v === "off") return false;
+  return undefined;
+}
+
+function resolveTuiMode(cliTui: boolean | undefined, envTui: string | undefined): boolean {
+  if (cliTui !== undefined) return cliTui;
+  const envVal = parseEnvBool(envTui);
+  if (envVal !== undefined) return envVal;
+  return !!process.stderr.isTTY;
+}
+
 function buildConfig(opts: SharedOptions): AgentCoreConfig {
   const config: AgentCoreConfig = {};
   if (opts.concurrency !== undefined || opts.rps !== undefined || opts.maxCost !== undefined) {
@@ -444,17 +470,37 @@ async function executeRun(opts: SharedOptions, run: RunOptions): Promise<void> {
 
 function startServer(opts: SharedOptions): void {
   const config = buildConfig(opts);
-  startCoreRuntime({
-    config,
-    loggerComponent: "cli",
-  });
+  const useTui = resolveTuiMode(opts.tui, process.env.ROBOPPI_TUI);
+  if (useTui && process.stderr.isTTY) {
+    // In Core stdio IPC mode, stdin is reserved for JSONL; use a passive renderer.
+    const tui = new CoreServerTui({ title: "roboppi core (IPC server)" });
+    tui.start();
+    process.on("exit", () => {
+      try { tui.stop(); } catch { /* ignore */ }
+    });
+    startCoreRuntime({
+      config,
+      loggerComponent: "cli",
+      logSink: tui.logSink,
+    });
+    return;
+  }
+
+  startCoreRuntime({ config, loggerComponent: "cli" });
 }
 
 // ── Main ──────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
 
+  // Default: show help in interactive TTY.
+  // Starting the Core IPC server is explicit via `roboppi server` (or by passing options).
+  if (argv.length === 0 && process.stdin.isTTY && process.stderr.isTTY) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+
   if (argv[0] === "workflow") {
     const { runWorkflowCli } = await import("./workflow/run.js");
     await runWorkflowCli(argv.slice(1));
@@ -467,6 +513,21 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Explicit server subcommand.
+  if (argv[0] === "server") {
+    const parsed = parseCliArgs(argv.slice(1));
+    if (parsed.opts.help) {
+      console.log(HELP_TEXT);
+      process.exit(0);
+    }
+    if (parsed.opts.version) {
+      console.log(`roboppi ${VERSION}`);
+      process.exit(0);
+    }
+    startServer(parsed.opts);
+    return;
+  }
+
   // Alias: `roboppi agent ...` == `roboppi run ...`
   const parsed = argv[0] === "agent"
     ? parseCliArgs(["run", ...argv.slice(1)])

src/core/agentcore.ts

@@ -64,7 +64,7 @@ export class AgentCore {
   private readonly activePermitsByJob = new Map<UUID, UUID>(); // jobId → permitId
   private started = false;
 
-  constructor(protocol: IpcProtocol, config?: AgentCoreConfig) {
+  constructor(protocol: IpcProtocol, config?: AgentCoreConfig, observability?: ObservabilityProvider) {
     this.protocol = protocol;
 
     // Initialize core components
@@ -75,7 +75,7 @@ export class AgentCore {
     this.permitGate = new PermitGate(this.budget, this.circuitBreakers, this.backpressure);
     this.watchdog = new Watchdog(config?.watchdog);
     this.escalation = new EscalationManager(config?.escalation);
-    this.observability = new ObservabilityProvider(config?.logLevel);
+    this.observability = observability ?? new ObservabilityProvider(config?.logLevel);
     this.workerGateway = new WorkerDelegationGateway();
 
     const logger = this.observability.createLogger("AgentCore");

src/core/core-runtime.ts

@@ -1,7 +1,7 @@
 import { JsonLinesTransport } from "../ipc/json-lines-transport.js";
 import { IpcProtocol } from "../ipc/protocol.js";
 import { AgentCore, type AgentCoreConfig } from "./agentcore.js";
-import { Logger } from "./observability.js";
+import { Logger, ObservabilityProvider, type LogSink } from "./observability.js";
 
 import { ProcessManager } from "../worker/process-manager.js";
 import { OpenCodeAdapter } from "../worker/adapters/opencode-adapter.js";
@@ -16,6 +16,7 @@ import { Readable, Writable } from "node:stream";
 export interface CoreRuntimeOptions {
   config?: AgentCoreConfig;
   loggerComponent?: string;
+  logSink?: LogSink;
 }
 
 function isNonInteractive(): boolean {
@@ -65,7 +66,7 @@ function parseDurationMs(input: string): number {
 
 export function startCoreRuntime(options: CoreRuntimeOptions = {}): void {
   const config = options.config;
-  const logger = new Logger(options.loggerComponent ?? "main", config?.logLevel ?? "info");
+  const logger = new Logger(options.loggerComponent ?? "main", config?.logLevel ?? "info", options.logSink);
 
   // Mark this process as the Core runtime for logging/diagnostics.
   if (!process.env.ROBOPPI_COMPONENT) process.env.ROBOPPI_COMPONENT = "core";
@@ -131,7 +132,8 @@ export function startCoreRuntime(options: CoreRuntimeOptions = {}): void {
 
   const transport = new JsonLinesTransport(stdin, stdout);
   const protocol = new IpcProtocol(transport);
-  const core = new AgentCore(protocol, config);
+  const observability = new ObservabilityProvider(config?.logLevel ?? "info", options.logSink);
+  const core = new AgentCore(protocol, config, observability);
 
   // Keepalive output for environments that kill silent subprocesses.
   // Enabled by default when non-interactive; can be overridden via env.

src/core/observability.ts

@@ -19,12 +19,20 @@ export interface LogEntry {
   data?: unknown;
 }
 
+export type LogSink = (entry: LogEntry) => void;
+
+const defaultLogSink: LogSink = (entry) => {
+  // Output to stderr (stdout is reserved for IPC)
+  process.stderr.write(JSON.stringify(entry) + "\n");
+};
+
 export class Logger {
   private _traceId?: string;
 
   constructor(
     private readonly component: string,
     private readonly minLevel: LogLevel = "debug",
+    private readonly sink: LogSink = defaultLogSink,
   ) {}
 
   setTraceId(traceId: string): void {
@@ -67,8 +75,7 @@ export class Logger {
     if (data !== undefined) {
       entry.data = data;
     }
-    // Output to stderr (stdout is reserved for IPC)
-    process.stderr.write(JSON.stringify(entry) + "\n");
+    this.sink(entry);
   }
 }
 
@@ -173,13 +180,15 @@ export class MetricsCollector {
 export class ObservabilityProvider {
   private readonly metrics = new MetricsCollector();
   private readonly minLevel: LogLevel;
+  private readonly sink: LogSink;
 
-  constructor(minLevel: LogLevel = "debug") {
+  constructor(minLevel: LogLevel = "debug", sink?: LogSink) {
     this.minLevel = minLevel;
+    this.sink = sink ?? defaultLogSink;
   }
 
   createLogger(component: string): Logger {
-    return new Logger(component, this.minLevel);
+    return new Logger(component, this.minLevel, this.sink);
   }
 
   getMetrics(): MetricsCollector {

src/tui/core-server-tui.ts

@@ -0,0 +1,135 @@
+import type { LogEntry, LogSink } from "../core/observability.js";
+import { RingBuffer } from "./ring-buffer.js";
+import type { TuiRenderer } from "./opentui-platform.js";
+import { PassiveAnsiRenderer } from "./passive-ansi-renderer.js";
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+function formatTime(ts: number): string {
+  const d = new Date(ts);
+  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+
+function safeJson(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+function truncate(s: string, max: number): string {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  if (max <= 3) return s.slice(0, max);
+  return s.slice(0, max - 3) + "...";
+}
+
+function levelColor(level: string): string {
+  switch (level) {
+    case "debug":
+      return "\x1b[90m";
+    case "info":
+      return "\x1b[36m";
+    case "warn":
+      return "\x1b[33m";
+    case "error":
+    case "fatal":
+      return "\x1b[31m";
+    default:
+      return "";
+  }
+}
+
+function formatLogLine(entry: LogEntry, width: number): string {
+  const t = formatTime(entry.timestamp);
+  const lvl = entry.level;
+  const lvlColored = `${levelColor(lvl)}${lvl}\x1b[0m`;
+  const base = `${t} ${lvlColored} ${entry.component}: ${entry.message}`;
+  const data = entry.data !== undefined ? ` ${truncate(safeJson(entry.data), Math.max(0, width - base.length - 1))}` : "";
+  return truncate(base + data, width);
+}
+
+export interface CoreServerTuiOptions {
+  title?: string;
+  renderer?: TuiRenderer;
+}
+
+export class CoreServerTui {
+  private readonly renderer: TuiRenderer;
+  private readonly title: string;
+
+  private readonly startedAt = Date.now();
+  private readonly logs = new RingBuffer<string>({ maxLines: 3000, maxBytes: 1024 * 1024 });
+  private renderTimer: ReturnType<typeof setInterval> | null = null;
+  private dirty = true;
+
+  private transport: string = "stdio";
+
+  constructor(opts: CoreServerTuiOptions = {}) {
+    this.renderer = opts.renderer ?? new PassiveAnsiRenderer();
+    this.title = opts.title ?? "roboppi core";
+  }
+
+  get logSink(): LogSink {
+    return (entry) => {
+      const width = (process.stderr.columns ?? 120);
+      this.logs.push(formatLogLine(entry, width));
+
+      // Best-effort: infer transport from the startup log.
+      if (entry.message.includes("awaiting IPC messages")) {
+        const data = entry.data;
+        if (data && typeof data === "object") {
+          const transport = (data as Record<string, unknown>).transport;
+          if (typeof transport === "string") this.transport = transport;
+        }
+      }
+
+      this.dirty = true;
+    };
+  }
+
+  start(): void {
+    this.renderer.start();
+
+    this.renderTimer = setInterval(() => {
+      if (!this.dirty) return;
+      this.dirty = false;
+      this.renderFrame();
+    }, 100);
+
+    this.renderFrame();
+  }
+
+  stop(): void {
+    if (this.renderTimer) {
+      clearInterval(this.renderTimer);
+      this.renderTimer = null;
+    }
+    this.renderer.destroy();
+  }
+
+  private renderFrame(): void {
+    const columns = process.stderr.columns ?? 80;
+    const rows = process.stderr.rows ?? 24;
+
+    const uptimeS = Math.floor((Date.now() - this.startedAt) / 1000);
+    const header1 = `\x1b[1m${this.title}\x1b[0m  transport=${this.transport}  uptime=${uptimeS}s`;
+    const header2 = `stdin/stdout: JSONL IPC (server)  logs: TUI (stderr)  help: --help  stop: Ctrl+C  plain: --no-tui`;
+    const sep = "-".repeat(Math.max(0, Math.min(columns, 120)));
+
+    const headerLines = [truncate(header1, columns), truncate(header2, columns), sep];
+    const bodyHeight = Math.max(0, rows - headerLines.length - 1);
+
+    const lines = this.logs.lines();
+    const visible = lines.slice(Math.max(0, lines.length - bodyHeight));
+    const padded: string[] = [];
+    for (const line of visible) padded.push(truncate(line, columns));
+    while (padded.length < bodyHeight) padded.unshift("");
+
+    const out = headerLines.join("\n") + "\n" + padded.join("\n") + "\n";
+    this.renderer.render(out);
+  }
+}