Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import React from 'react';
import { EventEmitter } from 'node:events';
import { render } from 'ink';
import fs from 'node:fs';
import { inspect } from 'node:util';
import path from 'node:path';
import { homedir } from 'node:os';
import { execSync, execFile, execFileSync } from 'node:child_process';
import type { ChannelMessage } from '../types/channel.js';
import { BaseChannel, type PermissionMode } from './base.js';
import { STEPS_PAUSED_BANNER, NO_CHANGES_BANNER } from '../core/completion-verdict.js';
import { logger } from '../utils/logger.js';
import { formatToolStep, formatToolResult } from '../utils/tool-label.js';
import { FILE_CHANGE_TOOLS } from '../utils/file-preview.js';
import { buildToolBlockDetail, isTranscriptTool, type ToolBlock } from '../ui/tool-block.js';
import type { ChatMessage, CompletionMeta, FileChangeSummary, ToolStep, PermissionPromptState, CurrentSessionInfo, SidebarSection, SkillInfo, SubAgentInfo, ProviderInfo, TokenInfo, SaverInfo, AppMode, WorkspaceState, WorkspaceTreeNode, WorkspaceGitFile, BackgroundTaskInfo, MercuryCodeGitState, MercuryCodeState, LiveActivityState, PlanStep } from '../ui/types.js';
import { TASK_SUMMARY_FILE_LIMIT } from '../ui/types.js';
import { TuiApp } from '../ui/App.js';
import { nextTip } from '../ui/tips.js';
import { ResilientTuiOutput } from '../ui/resilient-output.js';
import { PASTE_SENTINEL, FORWARD_DELETE_KEY } from '../ui/input-composer.js';
import { detectInkPatch, inkPatchWarning } from '../ui/ink-patch-check.js';
import { configureHardwareCursor } from '../ui/cursor-anchor.js';
/**
* Strip mouse-report escape sequences from terminal input before Ink sees
* them. Terminals emit SGR mouse sequences (ESC [ < b ; c ; r M/m) or legacy
* X10 ones (ESC [ M ...); scrolling a trackpad emits a flood of these, and
* Ink's keypress parser only partially consumes them, leaking fragments
* ("<0;34;12M") into the input box as garbage text.
*/
const MOUSE_SEQ_RE = /\x1b\[<\d+;\d+;\d+[Mm]|\x1b\[M[\x20-\x2f]*[\x40-\x6f]|\x1b\[\?100[0-7][hl]/g;
/**
* Markdown summary appended to the Mercury Code completion banner: what was
* done (a few bullets), how many files changed (paths capped at
* TASK_SUMMARY_FILE_LIMIT — the full list lives in git), and the next steps
* the developer might need to take. Short by design: the agent's full
* narration is already in the response above the banner.
*/
export function buildTaskSummary(opts: {
fileChanges: FileChangeSummary[];
doneSteps: string[];
verified: boolean;
uncommitted: boolean;
}): string {
const lines: string[] = [];
// Files first — the developer's top question is "what changed?".
if (opts.fileChanges.length > 0) {
const n = opts.fileChanges.length;
lines.push(`**Changes** · ${n} file${n !== 1 ? 's' : ''}${n > TASK_SUMMARY_FILE_LIMIT ? ` (showing ${TASK_SUMMARY_FILE_LIMIT})` : ''}`);
for (const f of opts.fileChanges.slice(0, TASK_SUMMARY_FILE_LIMIT)) {
const stats = f.added == null || f.removed == null ? 'new' : `+${f.added} −${f.removed}`;
lines.push(` ↳ ${f.path} · ${stats}`);
}
if (opts.fileChanges.length > TASK_SUMMARY_FILE_LIMIT) {
lines.push(` ↳ … ${opts.fileChanges.length - TASK_SUMMARY_FILE_LIMIT} more`);
}
}
const steps = opts.doneSteps.filter((label) => label.trim().length > 0).slice(0, 5);
if (steps.length > 0) {
lines.push('**What was done**');
for (const label of steps) lines.push(`• ${label}`);
}
const next: string[] = [];
if (opts.fileChanges.length > 0) {
if (!opts.verified) next.push('Run your test suite — these changes are not verified yet');
if (opts.uncommitted) next.push('Review the diff (`git diff`), then commit when ready');
}
if (next.length > 0) {
lines.push('**Next steps**');
for (const step of next) lines.push(`• ${step}`);
}
return lines.join('\n');
}
/**
* Parsed mouse event from an SGR/X10 sequence.
* click: press (or release of a press) without motion and without wheel.
*/
export interface MouseEvent {
button: number; // 0 left, 1 middle, 2 right, 64/65 wheel up/down
col: number; // 0-based
row: number; // 0-based
wheel: 'up' | 'down' | null;
click: boolean;
release: boolean;
motion: boolean;
}
/** Parse a single SGR or X10 mouse sequence into a MouseEvent. */
export function parseMouseSequence(seq: string): MouseEvent | null {
// SGR: ESC [ < b ; c ; r M/m
const sgr = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(seq);
if (sgr) {
const rawButton = parseInt(sgr[1], 10);
const col = parseInt(sgr[2], 10) - 1;
const row = parseInt(sgr[3], 10) - 1;
const isRelease = sgr[4] === 'm';
const motion = (rawButton & 32) !== 0;
const wheelBits = (rawButton & 64) !== 0;
const wheel: 'up' | 'down' | null = wheelBits ? ((rawButton & 1) === 0 ? 'up' : 'down') : null;
return {
button: rawButton & 3,
col,
row,
wheel,
click: !isRelease && !wheel && !motion,
release: isRelease,
motion,
};
}
// X10: ESC [ M cb+32 cx+32 cy+32
const x10 = /^\x1b\[M([\x20-\x2f])([\x20-\xff])([\x20-\xff])$/.exec(seq);
if (x10) {
const rawButton = x10[1].charCodeAt(0) - 32;
const col = x10[2].charCodeAt(0) - 33;
const row = x10[3].charCodeAt(0) - 33;
const wheelBits = (rawButton & 64) !== 0;
const motion = (rawButton & 32) !== 0;
const wheel: 'up' | 'down' | null = wheelBits ? ((rawButton & 1) === 0 ? 'up' : 'down') : null;
return {
button: rawButton & 3,
col,
row,
wheel,
click: !wheel && !motion,
release: false,
motion,
};
}
return null;
}
/** DECSET sequences to start (enable=true) or stop mouse reporting. */
export function mouseTrackingSequences(enable: boolean): string {
return enable
? '\x1b[?1000h\x1b[?1002h\x1b[?1006h'
: '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l';
}
/**
* Stateful mouse-sequence filter for the terminal input stream.
*
* Feeds complete mouse sequences (SGR/X10) to `onEvent`, passes every
* other byte through `write`, and HOLDS BACK partial escape prefixes so a
* sequence split across two stdin chunks is joined — never dropped,
* never leaked as keystrokes. A bounded holdback prevents a corrupt
* stream from growing memory without limit.
*/
/**
* Ink-facing stdin: forwards the Ink-required stream surface (setRawMode,
* ref/unref, setEncoding, readable/read) to the real terminal stream while
* feeding every chunk through the MouseSequenceFilter first. Ink never sees
* raw mouse sequences; wheel events become transcript scrolling in Mercury
* Code. Non-mouse bytes pass through byte-identical.
*/
class TtyStdinProxy extends EventEmitter {
private buffer = '';
private readonly real: NodeJS.ReadStream;
private readonly filter: MouseSequenceFilter;
readonly isTTY = true;
constructor(real: NodeJS.ReadStream, filter: MouseSequenceFilter) {
super();
this.real = real;
this.filter = filter;
this.real.on('data', (chunk: Buffer | string) => {
const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
this.filter.push(text);
});
this.real.on('end', () => this.emit('end'));
this.real.on('close', () => this.emit('close'));
}
/** Filter output lands here (called by the MouseSequenceFilter). */
write(s: string): void {
if (s.length === 0) return;
this.buffer += s;
this.emit('readable');
}
read(): string | null {
if (this.buffer.length === 0) return null;
const out = this.buffer;
this.buffer = '';
return out;
}
setEncoding(enc: BufferEncoding): this {
this.real.setEncoding(enc);
return this;
}
setRawMode(mode: boolean): this {
this.real.setRawMode(mode);
return this;
}
ref(): this { this.real.ref(); return this; }
unref(): this { this.real.unref(); return this; }
resume(): this { this.real.resume(); return this; }
pause(): this { this.real.pause(); return this; }
}
export class MouseSequenceFilter {
private buf = '';
/** Inside a bracketed paste (`ESC[200~` seen, `ESC[201~` not yet). */
private inPaste = false;
private flushTimer: ReturnType<typeof setTimeout> | null = null;
private static readonly SGR = /^\x1b\[<\d+;\d+;\d+[Mm]/;
private static readonly X10 = /^\x1b\[M[\x20-\x2f][\x20-\xff][\x20-\xff]/;
private static readonly DEC = /^\x1b\[\?100[0-7][hl]/;
private static readonly CSI_COMPLETE = /^\x1b\[[\d;<]*[A-Za-z]/;
private static readonly PASTE_START = /^\x1b\[200~/;
private static readonly PASTE_END = /^\x1b\[201~/;
/** Partial `ESC[201~` at the end of a paste chunk — wait for the rest. */
private static readonly PASTE_END_PARTIAL = /^\x1b(\[(2(0(1)?)?)?)?$/;
/** Any ANSI escape inside pasted text (never meaningful as input). */
private static readonly PASTE_ANSI = /\x1b(\[[0-9;?<>=]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])?/g;
private static readonly MAX_HOLDBACK = 64;
/**
* A held-back prefix that is not completed within this window is a real
* keypress (a lone Esc, Alt+key) and is released as-is. Terminals deliver
* a complete sequence in one read or within a millisecond or two; 35 ms
* is the conventional ESC-disambiguation delay (vim's ttimeoutlen scale).
*/
static readonly HOLDBACK_FLUSH_MS = 35;
/**
* Keys Ink either cannot parse or cannot tell apart, rewritten to
* sequences the shared composer understands (see input-composer.tsx):
* Shift+Enter / Ctrl+Enter in every common encoding → Ctrl+N (newline)
* the real Delete key (ESC[3~) → FORWARD_DELETE_KEY (Ink folds it into
* `key.delete` together with \x7f, which is Backspace on macOS/Linux)
*/
private static readonly KEY_REWRITES: ReadonlyArray<readonly [RegExp, string]> = [
[/^\x1b\[13;[25]u/, '\x0e'], // kitty keyboard protocol
[/^\x1b\[27;[25];13~/, '\x0e'], // xterm modifyOtherKeys
[/^\x1b\r/, '\x0e'], // ESC CR (iTerm2 / Alt+Enter)
[/^\x1b\[3~/, FORWARD_DELETE_KEY],
// Home / End: Ink names them but hands the composer an empty `input`
// with no `key.home`/`key.end` flag, so they were dead keys. Readline
// Ctrl+A / Ctrl+E are what the composer binds to line start / end.
[/^\x1b(\[(1~|H)|OH)/, '\x01'],
[/^\x1b(\[(4~|F)|OF)/, '\x05'],
];
constructor(
private onEvent: (ev: MouseEvent) => void,
private write: (s: string) => void,
) {}
/** Feed a raw chunk from the terminal; returns nothing, side-effects only. */
push(chunk: Buffer | string): void {
this.buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
this.drain();
}
private drain(): void {
let out = '';
let paste = '';
let i = 0;
const flushOut = () => { if (out) { this.write(out); out = ''; } };
const flushPaste = () => {
if (paste) {
this.write(PASTE_SENTINEL + paste.replace(MouseSequenceFilter.PASTE_ANSI, ''));
paste = '';
}
};
while (i < this.buf.length) {
const rest = this.buf.slice(i);
if (this.inPaste) {
if (rest[0] !== '\x1b') {
const esc = rest.indexOf('\x1b');
const text = esc < 0 ? rest : rest.slice(0, esc);
paste += text;
i += text.length;
continue;
}
const end = MouseSequenceFilter.PASTE_END.exec(rest)?.[0];
if (end) {
this.inPaste = false;
flushPaste();
i += end.length;
continue;
}
if (MouseSequenceFilter.PASTE_END_PARTIAL.test(rest)) break;
// An escape inside the paste: keep it in the payload (stripped
// from the text later) and move on.
paste += rest[0];
i += 1;
continue;
}
if (rest[0] !== '\x1b') {
out += rest[0];
i += 1;
continue;
}
const seq = MouseSequenceFilter.SGR.exec(rest)?.[0]
?? MouseSequenceFilter.X10.exec(rest)?.[0]
?? MouseSequenceFilter.DEC.exec(rest)?.[0];
if (seq) {
const ev = parseMouseSequence(seq);
if (ev) {
try { this.onEvent(ev); } catch { /* handler must never crash input */ }
}
i += seq.length;
continue;
}
const pasteStart = MouseSequenceFilter.PASTE_START.exec(rest)?.[0];
if (pasteStart) {
// Keystrokes typed before the paste must reach Ink before the
// paste payload, as their own chunk.
flushOut();
this.inPaste = true;
i += pasteStart.length;
continue;
}
let rewritten = false;
for (const [pattern, replacement] of MouseSequenceFilter.KEY_REWRITES) {
const m = pattern.exec(rest)?.[0];
if (m) {
// A rewritten key is a keystroke of its own: Ink parses a chunk
// as ONE key, so it must not be glued to surrounding text.
flushOut();
this.write(replacement);
i += m.length;
rewritten = true;
break;
}
}
if (rewritten) continue;
// X10 mouse in flight (ESC [ M + 0-2 pending payload bytes) — MUST be
// tested before the generic CSI pass-through, because 'M' is a valid
// CSI final byte and would otherwise leak the prefix downstream.
if (/^\x1b\[M[\x20-\xff]{0,2}$/.test(rest)) {
break;
}
// Complete non-mouse CSI (arrow keys etc.) — pass through untouched.
const csi = MouseSequenceFilter.CSI_COMPLETE.exec(rest)?.[0];
if (csi) {
out += csi;
i += csi.length;
continue;
}
// Incomplete escape sequence — hold it back and wait for the rest.
// Covers CSI starts (ESC [ 3 2 ...) and SGR mouse starts (ESC [ < 6 4 ;).
if (/^\x1b(\[[\d;<\?<>]*)?$/.test(rest)) {
break;
}
// Unknown escape byte — pass it through so Ink's parser sees it.
out += rest[0];
i += 1;
}
this.buf = i >= this.buf.length ? '' : this.buf.slice(i);
// Overflow guard: an unterminated garbage prefix must not grow forever.
// Flush it, stripping ESC bytes so terminal/Ink never sees raw ones.
if (this.buf.length > MouseSequenceFilter.MAX_HOLDBACK) {
this.buf = '';
}
if (this.inPaste) flushPaste();
flushOut();
this.armHoldbackFlush();
}
/**
* A held-back prefix is either the head of a sequence still in flight or
* a real key (a lone Esc, Alt+letter). Release it after a short delay so
* Esc reaches Ink on its own instead of fusing with the NEXT keystroke.
*/
private armHoldbackFlush(): void {
if (this.flushTimer) {
clearTimeout(this.flushTimer);
this.flushTimer = null;
}
if (this.buf.length === 0 || this.inPaste) return;
this.flushTimer = setTimeout(() => {
this.flushTimer = null;
if (this.buf.length === 0 || this.inPaste) return;
const held = this.buf;
this.buf = '';
// A bare ESC is the Escape key; anything longer is an unknown
// sequence whose bytes Ink can still interpret (Alt+key etc.).
this.write(held);
}, MouseSequenceFilter.HOLDBACK_FLUSH_MS);
(this.flushTimer as { unref?: () => void }).unref?.();
}
/** Drop timers (tests / teardown). */
dispose(): void {
if (this.flushTimer) clearTimeout(this.flushTimer);
this.flushTimer = null;
}
}
/** DECSET: bracketed paste on/off. On, the terminal wraps pasted text in
* `ESC[200~ … ESC[201~` so the filter can insert it literally. */
export function bracketedPasteSequences(enable: boolean): string {
return enable ? '\x1b[?2004h' : '\x1b[?2004l';
}
/** Status-bar hint shown while the TUI is frozen (Ctrl+S scroll lock). The
* substring '⏸ frozen' is also the ink freeze-gate marker (the armed window
* lets through only the frame that carries it) — keep them in sync. */
export const TUI_FROZEN_HINT_MARKER = '⏸ frozen';
/** One-line transcript marker written when Esc interrupts a running turn. */
export const INTERRUPTED_MARKER = '⏹ Interrupted';
export interface TuiState {
mode: AppMode;
viewMode: 'balanced' | 'detailed';
chatMessages: ChatMessage[];
toolSteps: ToolStep[];
/** Live plan checklist maintained by the agent via the update_plan tool. */
planProgress: PlanStep[] | null;
/** Live reasoning preview while the model thinks before speaking. */
thinkingPreview: string | null;
isThinking: boolean;
permissionPrompt: PermissionPromptState | null;
agentName: string;
version: string;
provider: ProviderInfo | null;
tokenInfo: TokenInfo | null;
skills: SkillInfo[];
subAgents: SubAgentInfo[];
sidebarSections: SidebarSection[];
programmingMode: import('../core/programming-mode.js').ProgrammingModeState;
projectContext: string | null;
permissionMode: PermissionMode;
workspace: WorkspaceState | null;
backgroundTasks: BackgroundTaskInfo[];
web: { enabled: boolean; port: number } | null;
saverInfo: SaverInfo | null;
/** Last completed step log, preserved after completion wipes toolSteps. Ctrl+D dumps this. */
lastStepLog: ToolStep[] | null;
/** Elapsed ms for the last completed task. */
lastStepLogElapsed: number | null;
currentSession: CurrentSessionInfo | null;
/** Mercury Code (full-screen `/code`) state — null unless active. */
mercuryCode: MercuryCodeState | null;
/** Double-Esc detection for Mercury Code exit. */
exitEscArmed: boolean;
/** Real-time activity phase (what the agent is doing right now), or null when idle. */
liveActivity: LiveActivityState | null;
/**
* Mercury Code status-verb pool for the live status row. null until the
* agent's one-shot LLM refinement lands (session start shows the plain
* static label); populated with LLM verbs (or the keyword fallback after a
* failed generation) and cleared on exitMercuryCode.
*/
statusVerbs: string[] | null;
/** TUI frame freeze (scroll lock): all frame writes stop so the user can
* scroll/copy freely while the chat continues underneath. Ctrl+S toggles. */
tuiFrozen: boolean;
/** A newer Mercury version the background check found — shown as a tiny
* bottom-bar indicator (⬆ vX) in Mercury Code until ignored. */
updateAvailable: string | null;
/** What a desktop plugin (Optimus) is doing right now, e.g. "🎙 Optimus listening"; null when idle. */
desktopActivity: string | null;
/** Active Mercury Bot chat — transcript is swapped to the bot's thread. */
botChat: { botId: string; botName: string } | null;
/** Per-bot real-time activity (what each bot is doing RIGHT NOW) — rendered
* as a live region in an open bot thread, keyed by bot id. */
botLiveActivity: Record<string, LiveActivityState>;
/** Per-bot streaming tails (what each bot is THINKING / replying right now,
* from the bot turn's reasoning/text deltas) — rendered live in its thread. */
botStreamTails: Record<string, { reasoning: string; text: string }>;
/** Live bot roster (drives `/bots` argument autocomplete and badges). */
botRoster: Array<{ id: string; name: string; state: string; needsYou: boolean; fleetRole?: 'lead' | 'crew'; parent?: string }>;
}
const defaultState: TuiState = {
mode: 'splash',
viewMode: 'balanced',
chatMessages: [],
toolSteps: [],
planProgress: null,
thinkingPreview: null,
isThinking: false,
permissionPrompt: null,
agentName: 'Mercury',
version: '1.1.5',
provider: null,
tokenInfo: null,
skills: [],
subAgents: [],
sidebarSections: [],
programmingMode: 'off',
projectContext: null,
permissionMode: 'ask-me',
workspace: null,
backgroundTasks: [],
web: null,
saverInfo: null,
lastStepLog: null,
lastStepLogElapsed: null,
currentSession: null,
mercuryCode: null,
exitEscArmed: false,
liveActivity: null,
statusVerbs: null,
tuiFrozen: false,
updateAvailable: null,
desktopActivity: null,
botChat: null,
botLiveActivity: {},
botStreamTails: {},
botRoster: [],
};
function shallowEqualSubAgents(a: SubAgentInfo[], b: SubAgentInfo[]): boolean {
if (a.length !== b.length) return false;
for (let i = 0; i < a.length; i++) {
if (a[i].id !== b[i].id || a[i].status !== b[i].status || a[i].progress !== b[i].progress) return false;
}
return true;
}
function shallowEqualBgTasks(a: BackgroundTaskInfo[], b: BackgroundTaskInfo[]): boolean {
if (a.length !== b.length) return false;
for (let i = 0; i < a.length; i++) {
if (a[i].id !== b[i].id || a[i].status !== b[i].status || a[i].runningMs !== b[i].runningMs) return false;
}
return true;
}
export class CLIChannel extends BaseChannel {
readonly type = 'cli' as const;
private agentName: string;
private inkInstance: ReturnType<typeof render> | null = null;
private restoreConsole: (() => void) | null = null;
private inputHandler: ((text: string) => void) | null = null;
private exitHandler: (() => void) | null = null;
/** Esc-during-a-turn: installed by the boot path with the agent's stop
* routine (the same one `/stop` calls). Null until set. */
private interruptHandler: (() => unknown) | null = null;
/**
* Pending interactive prompts, keyed by prompt id. Several callers can
* prompt concurrently (the foreground turn, sub-agents, bots): a single
* resolver slot was overwritten by the newest prompt and the earlier
* promises never settled. Every prompt now keeps its own resolver; the
* TUI shows them in arrival order — `state.permissionPrompt` is the one
* on screen, `promptQueue` holds the rest.
*/
private promptResolvers = new Map<string, (value: string | boolean) => void>();
private promptQueue: PermissionPromptState[] = [];
private promptSeq = 0;
private menuDepth = 0;
private menuAbortController: AbortController | null = null;
private heartbeatMsgId: string | null = null;
// Mercury Bot chat (mode-scoped transcript swap, §3.3): the bot's thread
// replaces the transcript on screen; main-agent traffic parks in
// mainTranscript until /chat restores it.
private activeBotId: string | null = null;
private mainTranscript: ChatMessage[] | null = null;
private botTranscripts = new Map<string, ChatMessage[]>();
/** Set while the input handler dispatches a bot-chat message downstream. */
private pendingBotChatTarget: string | null = null;
// Per-turn file-change attribution: file-tool calls (write/create/edit/
// delete) with their args path. Committed entries surface in the completion
// banner; a general chat turn that touches no files stays clean.
private pendingTurnFiles = new Map<string, string>();
private committedTurnFiles = new Set<string>();
// Mercury Code tool transcript: args of running steps (by step id), kept
// until completion builds the step's transcript block.
private toolArgs = new Map<string, Record<string, any>>();
// The agent message currently being streamed. A tool call starting
// mid-stream closes it (cutStreamSegment) so the tool's block lands after
// the text that preceded it, and later text opens a fresh message.
private streamSegment: { id: string; text: string; started: boolean; lastRender: number } | null = null;
// Full excerpts of collapsed tool blocks, newest last, for ctrl+o. Bounded:
// only the most recent blocks are expandable.
private expandableTools: Array<{ block: ToolBlock; full: { lang: string; lines: string[] } }> = [];
private static readonly MAX_EXPANDABLE_TOOLS = 20;
/** update-notice helpers, imported lazily (a static import would pull
* cli/daemon.js into an import cycle through channels/cli.ts). */
private updateNoticeApiPromise: Promise<any> | null = null;
private updateNoticeApi() {
if (!this.updateNoticeApiPromise) {
this.updateNoticeApiPromise = import('../cli/update-notice.js');
}
return this.updateNoticeApiPromise;
}
private stepCount = 0;
private stepStartTime = 0;
private state: TuiState = { ...defaultState };
private spotifyClient: any = null;
private statusPoller: NodeJS.Timeout | null = null;
private statusPollerBusy = false;
private mouseEnabled = false;
private mouseHandler: ((ev: MouseEvent) => void) | null = null;
private tuiOutput: ResilientTuiOutput | null = null;
private stateListeners = new Set<() => void>();
private rerenderMicrotaskQueued = false;
private tuiExitImmediate: NodeJS.Immediate | null = null;
private exitEscArmed = false;
private statusProviders: {
tokens?: () => { used: number; budget: number; percentage: number };
saver?: () => { state: import('../core/saver-mode.js').SaverModeState; savedToday: number; savedLifetime: number };
subAgents?: () => SubAgentInfo[];
bgTasks?: () => BackgroundTaskInfo[];
botRoster?: () => Array<{ id: string; name: string; state: string; needsYou: boolean }>;
} = {};
constructor(agentName: string = 'Mercury') {
super();
this.agentName = agentName;
this.state.agentName = agentName;
}
setAgentName(name: string): void {
this.agentName = name;
this.update({ agentName: name });
}
async start(): Promise<void> {
this.ready = true;
logger.info('CLI channel started (Ink TUI)');
}
async stop(): Promise<void> {
this.stopStatusPoller();
this.setMouseEnabled(false);
if (this.tuiExitImmediate) {
clearImmediate(this.tuiExitImmediate);
this.tuiExitImmediate = null;
}
this.teardownTui();
this.ready = false;
}
private teardownTui(): void {
// The gate must never survive teardown: ink's final unmount writes
// (log.done(), cursor restore) have to reach the terminal.
this.writeGateFrozen = false;
this.frozenHintPending = false;
this.tuiFrozen = false;
this.frameGateSet({ armed: false, frozen: false, marker: '' });
const inkInstance = this.inkInstance;
this.inkInstance = null;
// Unmount may throw on a corrupted Yoga heap; shutdown must still
// release the output wrapper and restore the terminal.
try { inkInstance?.unmount(); } catch { /* best effort teardown */ }
this.restoreConsole?.();
this.restoreConsole = null;
this.stateListeners.clear();
this.tuiOutput?.dispose();
this.tuiOutput = null;
this.releaseRawMode();
this.restoreTerminal();
}
private scheduleTuiExit(): void {
if (this.tuiExitImmediate) return;
this.setMouseEnabled(false);
// useInput runs inside React's batchedUpdates. Calling Ink.unmount()
// there re-enters the reconciler and can invalidate Yoga nodes while
// they are still being laid out. Leave React's callback stack first.
this.tuiExitImmediate = setImmediate(() => {
this.tuiExitImmediate = null;
this.teardownTui();
this.exitHandler?.();
});
}
private releaseRawMode(): void {
if (!process.stdin.isTTY) return;
const stdin = process.stdin as NodeJS.ReadStream;
if (typeof stdin.setRawMode !== 'function') return;
try {
stdin.setRawMode(false);
} catch {
// Ignore teardown failures.
}
}
private restoreRawModeAfterMenu(): void {
if (!process.stdin.isTTY) return;
const stdin = process.stdin as NodeJS.ReadStream;
if (stdin.isRaw === true || typeof stdin.setRawMode !== 'function') return;
try {
// Arrow menus temporarily own stdin and disable raw mode on exit.
// Do not call resume(): Ink consumes stdin through a readable listener.
stdin.setRawMode(true);
} catch {
// Ink will surface input failures if the TTY is no longer available.
}
}
/** Scroll-lock (freeze) bookkeeping. `tuiFrozen` is the user-facing state;
* `writeGateFrozen` is the actual frame gate (opens after the hint frame);
* `frozenHintPending` lets the one hint frame through the gate. */
private tuiFrozen = false;
private writeGateFrozen = false;
private frozenHintPending = false;
private update(partial: Partial<TuiState>): void {
// Blocking interactions must never be invisible: auto-resume BEFORE the
// update so the frame that carries the prompt goes out — and the
// tuiFrozen flag must clear in the SAME state merge, otherwise the
// resumed frame still renders the frozen status bar.
if (this.writeGateFrozen && (partial.permissionPrompt || partial.mercuryCode?.exitConfirm)) {
this.unfreezeForInteraction();
partial = { ...partial, tuiFrozen: false };
}
this.state = { ...this.state, ...partial };
this.rerender();
}
/**
* Freeze/unfreeze the TUI frame stream (scroll lock, Ctrl+S). While frozen
* the agent keeps streaming — state keeps merging in this.update — but
* rerender() stops notifying React, so ink writes nothing and the user's
* terminal is untouched: they can scroll, read, and drag-select freely in
* native scrollback while the chat is in progress. Resume emits one fresh
* frame (the ink diff-render rewrites only rows that changed since the
* freeze frame).
*
* Freezing shows the status hint FIRST (one frame), then closes the write
* gate after ink's 32ms onRender throttle has had its chance — so the user
* always sees what happened. Auto-resume on permission prompts / exit
* confirms: they own the keyboard and must never be invisible.
*/
setTuiFrozen(frozen: boolean): void {
if (frozen === this.tuiFrozen) return;
this.tuiFrozen = frozen;
if (frozen) {
this.frozenHintPending = true;
// Pass 1: write the hint frame (gate still open, hint marker armed).
this.frameGateSet({ armed: true, frozen: false, marker: TUI_FROZEN_HINT_MARKER });
this.update({ tuiFrozen: true });
// ink's onRender is throttled to 32ms; 90ms safely covers the flush.
const timer = setTimeout(() => {
this.frozenHintPending = false;
this.writeGateFrozen = true;
this.frameGateSet({ armed: false, frozen: true, marker: '' });
}, 90);
timer.unref?.();
} else {
this.writeGateFrozen = false;
this.frozenHintPending = false;
this.frameGateSet({ armed: false, frozen: false, marker: '' });
this.update({ tuiFrozen: false });
}
}
/** The ink patch's freeze gate (undefined when ink is unpatched — e.g. a
* dev checkout where the patch applier hasn't run). */
private get frameGate(): { frozen: boolean; armed: boolean; marker: string } | undefined {
return (globalThis as any).__mercuryFrameGate;
}
private frameGateSet(gate: { frozen: boolean; armed: boolean; marker: string }): void {
const g = this.frameGate;
if (g) Object.assign(g, gate);
}
/** Resume rendering: a blocking interaction (prompt/confirm) or explicit
* unfreeze arrived. Opens the write gate before the state update so the
* frame that carries the interaction is not dropped. Called from inside
* update() — the partial itself must carry tuiFrozen: false so the frame
* renders the resumed state. */
private unfreezeForInteraction(): void {
if (!this.tuiFrozen && !this.writeGateFrozen) return;
this.writeGateFrozen = false;
this.frozenHintPending = false;
this.tuiFrozen = false;
this.frameGateSet({ armed: false, frozen: false, marker: '' });
}
/** useSyncExternalStore contract: read the latest immutable state snapshot. */
// ---- Mercury Bot chat (per-bot transcripts) ------------------------------
/** Open a bot's chat: swap the on-screen transcript to the bot's thread.
* `history` hydrates a thread with no in-memory transcript (journal tail). */
enterBotChat(botId: string, botName: string, history?: Array<{ content: string; timestamp: number }>): void {
if (this.activeBotId === botId) return;
if (this.activeBotId) {
this.botTranscripts.set(this.activeBotId, [...this.state.chatMessages]);
} else {
this.mainTranscript = [...this.state.chatMessages];
}
this.activeBotId = botId;
// In-memory transcript wins (live session continuity); otherwise hydrate
// from the durable journal history the caller provides, so a thread
// opened after a restart (or after the bot worked unattended) shows what
// happened instead of an empty room. Bounded: caller passes ≤10 records.
const seed: ChatMessage[] = (this.botTranscripts.get(botId) ?? [
{
id: `bot-open-${Date.now().toString(36)}`,
role: 'system',
content: `🤖 **${botName}** bot chat — everything you type here goes to the bot (runs outside the main conversation). \`/chat\` returns to the main transcript.`,
timestamp: Date.now(),
},
...(history ?? []).map((h, i) => ({
id: `bot-hist-${botId}-${i}-${h.timestamp.toString(36)}`,
role: 'system' as const,
content: `📜 ${h.content}`,
timestamp: h.timestamp,
})),
]);
this.botTranscripts.set(botId, seed);
this.trimAndSetMessages(seed, { botChat: { botId, botName }, isThinking: false, liveActivity: null });
}
/** Leave the bot chat and restore the main transcript. */
exitBotChat(): void {
if (!this.activeBotId) return;
this.botTranscripts.set(this.activeBotId, [...this.state.chatMessages]);
const main = this.mainTranscript ?? [];
this.activeBotId = null;
this.mainTranscript = null;
this.trimAndSetMessages(main, { botChat: null, isThinking: false, liveActivity: null });
}
getActiveBotChat(): { botId: string; botName: string } | null {
return this.activeBotId ? this.state.botChat : null;
}
/** Agent-side marker: the in-flight input was dispatched from a bot chat. */
consumePendingBotChatTarget(): string | null {
const target = this.pendingBotChatTarget;
this.pendingBotChatTarget = null;
return target;
}
private appendBotMessage(botId: string, msg: ChatMessage): void {
const existing = this.botTranscripts.get(botId) ?? [];
const updated = [...existing.slice(-CLIChannel.MAX_CHAT_MESSAGES + 1), msg];
this.botTranscripts.set(botId, updated);
if (this.activeBotId === botId) {
this.trimAndSetMessages(updated, { isThinking: false, liveActivity: null });
}
}
getTuiStateSnapshot = (): TuiState => {
return this.state;
};
/** useSyncExternalStore contract: subscribe to state changes. */
subscribeToTuiState = (listener: () => void): (() => void) => {
this.stateListeners.add(listener);
return () => {
this.stateListeners.delete(listener);
};
};
/** Update an existing chat message's content in place (by ID). */
private updateMessage(id: string, content: string, extra?: Partial<ChatMessage>): void {
this.update({
chatMessages: this.state.chatMessages.map((m) =>
m.id === id ? { ...m, content: content.slice(0, CLIChannel.MAX_MESSAGE_CHARS), timestamp: Date.now(), ...extra } : m,
),
});
}
private rerender(): void {
// Freeze gate: state has already merged (this.update) — only the frame
// is suppressed. React never re-renders while frozen, so <Static> never
// commits new items (committing without printing would lose finalized
// messages — Static marks keys committed at the React level). The one
// exception is the armed hint window: the freeze hint frame must go out
// so the user sees the frozen state.
if (this.writeGateFrozen && !this.frozenHintPending) return;
// Notify React subscribers instead of calling inkInstance.rerender().
// Imperative re-rendering enters the reconciler synchronously from
// arbitrary call sites and races React's own renders (spinner/size
// timers) — the resulting re-entrant commit corrupted Yoga's WASM heap
// ("memory access out of bounds").
//
// Notifications are deferred to the event loop's check phase and
// coalesced: update() is sometimes called from inside React's own
// commit phase (e.g. the scroll-clamp effect calls back into channel
// state). A synchronous listener call there would re-enter the
// reconciler mid-work — React's "Should not already be working." error.
// setImmediate (not queueMicrotask) is deliberate: microtasks drain
// before timers, so under streaming render pressure a memory-guard
// interval could never fire and a runaway task reached a fatal V8 OOM.
// The check phase lets pending timers run between render batches.
if (this.rerenderMicrotaskQueued) return;
this.rerenderMicrotaskQueued = true;
setImmediate(() => {
this.rerenderMicrotaskQueued = false;
this.stateListeners.forEach((listener) => listener());
});
}
/**
* Restore the terminal to a sane, non-mouse state. Called on every exit
* path (graceful stop, TUI exit, crash handlers) so a crashed Mercury
* never leaves the shell spewing mouse-report garbage.
*/
restoreTerminal(): void {
try {
process.stdout.write(mouseTrackingSequences(false) + bracketedPasteSequences(false) + '\x1b[?25h');
} catch { /* not a TTY */ }
}
/**
* Install the routine Esc calls to interrupt the running turn. The boot
* path wires it to the agent's `stopAllWork('stopped')` — exactly what
* typing `/stop` does — so the channel never reaches into the agent.
*/
setInterruptHandler(handler: (() => unknown) | null): void {
this.interruptHandler = handler;
}
/** True while the agent is mid-turn (thinking, running a tool, or reporting a live phase). */
isTurnRunning(): boolean {
return this.state.isThinking
|| this.state.toolSteps.some((s) => s.status === 'running')
|| this.state.liveActivity !== null;
}
/**
* Interrupt the running turn (Esc). Writes a one-line "Interrupted"
* marker into the transcript and invokes the stop routine. Returns false
* (and does nothing) when no turn is running or no handler is installed.
*/
interruptTurn(): boolean {
if (!this.interruptHandler || !this.isTurnRunning()) return false;
const marker: ChatMessage = {
id: `interrupt-${Date.now().toString(36)}`,
role: 'system',
content: INTERRUPTED_MARKER,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, marker], { liveActivity: null, thinkingPreview: null });
try {
const result = this.interruptHandler();
if (result && typeof (result as Promise<unknown>).catch === 'function') {
(result as Promise<unknown>).catch((err) => logger.warn({ err }, 'interrupt handler failed'));
}
} catch (err) {
logger.warn({ err }, 'interrupt handler failed');
}
return true;
}
mountTUI(onInput: (text: string) => void, spotifyClient?: any, onExit?: any): void {
this.spotifyClient = spotifyClient ?? null;
this.exitHandler = onExit ?? null;
if (this.tuiExitImmediate) {
clearImmediate(this.tuiExitImmediate);
this.tuiExitImmediate = null;
}
// Ink reads through the filtered proxy: mouse sequences never reach the
// input box, and wheel events drive Mercury Code scrolling.
this.installStdinProxy();
this.inputHandler = (text: string) => {
const trimmed = text.trim();
// Bot chat: /chat exits back to the main transcript; plain text goes
// to the bot as `/bot <id> <text>` (durable enqueue, reply lands here).
if (this.activeBotId) {
if (trimmed === '/chat' || trimmed === '/c') {
this.exitBotChat();
this.update({ mode: 'chat' });
return;
}
if (trimmed && !trimmed.startsWith('/')) {
const wrapped = `/bot ${this.activeBotId} ${trimmed}`;
this.pendingBotChatTarget = this.activeBotId;
try {
onInput(wrapped);
} finally {
this.pendingBotChatTarget = null;
}
return;
}
// /skip during persona capture routes INTO the bot thread so the
// agent's capture state machine sees it — a bare slash here would
// exit the chat and strand the pending persona (the onboarding
// prompt explicitly tells the user to send /skip).
if (trimmed === '/skip') {
const wrapped = `/bot ${this.activeBotId} /skip`;
this.pendingBotChatTarget = this.activeBotId;
try {
onInput(wrapped);
} finally {
this.pendingBotChatTarget = null;
}
return;
}
// /persona inside a bot chat rewrites to the explicit setter so the
// persona flow works without leaving the bot thread. Bare /persona
// arms the capture (next message becomes the persona) — it must NOT
// degrade to the /bots roster.
if (trimmed.startsWith('/persona')) {
const personaText = trimmed.slice('/persona'.length).trim();
onInput(personaText
? `/bots persona ${this.activeBotId} ${personaText}`
: `/bots persona ${this.activeBotId}`);
return;
}
// /bots control commands STAY inside the bot thread: the agent routes
// their replies into this transcript via the pending bot-chat target
// (same mechanism as /bot dispatch) — the roster, journal, inbox etc.
// all render here. `/bots open <other-id>` naturally swaps threads.
if (trimmed.startsWith('/bots')) {
this.pendingBotChatTarget = this.activeBotId;
try {
onInput(trimmed);
} finally {
this.pendingBotChatTarget = null;
}
return;
}
// Any other slash command exits the bot chat first (review D2):
// command replies route to the main transcript and would otherwise
// be invisible from inside the bot thread.
if (trimmed.startsWith('/')) {
this.exitBotChat();
}
}
if (trimmed === '/chat' || trimmed === '/c') {
// Returning from Mercury Code must tear down its state (mouse mode,
// scroll offset, programming mode) — not just flip the view. A bare
// mode switch left mercuryCode set and programmingMode dangling.
if (this.state.mode === 'mercury-code') this.exitMercuryCode();
else this.update({ mode: 'chat' });
return;
}
// View-only: handled here, never sent to the agent.
if (trimmed === '/code expand') {
this.expandLastToolOutput();
return;
}
// Instant switch back to regular chat — no exit-confirm dance. The
// confirm exists to guard the Esc-Esc path against accidental exits
// mid-task; an explicit command is deliberate by definition.
if (trimmed === '/code chat' || trimmed === '/code back') {
if (this.state.mercuryCode) this.exitMercuryCode();
return;
}
// `/code` flows to the agent so core ProgrammingMode + view stay in
// sync (agent calls back into enterMercuryCode).
// Internal Mercury Code view commands (issued by the TUI itself).
if (trimmed.startsWith('/mc ')) {
const sub = trimmed.slice(4).trim();
// scroll-set MUST be matched before the generic scroll- prefix — the
// generic branch parses 'scroll-set N' as delta 'set N' (NaN) and
// returns, which silently killed the scroll-clamp loop: after a
// history trim the stored offset could exceed the shrunken
// transcript forever, leaving the viewport stuck on the last rows
// ("can't scroll, only see the code").
if (sub.startsWith('scroll-set ')) {
const distance = parseInt(sub.slice(11), 10);
if (Number.isFinite(distance)) {
const mcRef = this.state.mercuryCode;
if (mcRef && distance !== mcRef.scrollOffset) {
this.update({ mercuryCode: { ...mcRef, scrollOffset: distance } });
}
}
return;
}
if (sub === 'scroll' || sub.startsWith('scroll ') || sub.startsWith('scroll-')) {
const arg = sub.startsWith('scroll-') ? sub.slice(7) : sub.slice(6).trim();
const delta = arg.startsWith('-') ? -parseInt(arg.slice(1), 10) : parseInt(arg, 10);
if (Number.isFinite(delta)) this.scrollMercuryCode(delta);
return;
}
if (sub === 'live') { this.scrollMercuryCodeToLive(); return; }
// Scroll lock (freeze): stop all frame writes so the user can scroll
// and copy freely in native scrollback while the chat streams on.
if (sub === 'freeze' || sub === 'resume' || sub === 'unfreeze') { this.setTuiFrozen(sub === 'freeze'); return; }
if (sub === 'freeze-toggle') { this.setTuiFrozen(!this.state.tuiFrozen); return; }
if (sub === 'expand') { this.expandLastToolOutput(); return; }
if (sub === 'esc-arm') {
this.exitEscArmed = true;
// Auto-disarm after 1.5s so Esc-Esc window is bounded.
setTimeout(() => { if (this.exitEscArmed) { this.exitEscArmed = false; this.update({ exitEscArmed: false }); } }, 1500);
this.update({ exitEscArmed: true });
return;
}
if (sub === 'exit-arm') { this.exitEscArmed = false; this.update({ exitEscArmed: false }); this.setMercuryCodeExitConfirm(true); return; }
if (sub === 'exit-cancel') { this.exitEscArmed = false; this.update({ exitEscArmed: false }); this.setMercuryCodeExitConfirm(false); return; }
if (sub === 'exit-confirm' || sub === 'exit-force') {
this.exitEscArmed = false;
this.update({ exitEscArmed: false });
this.exitMercuryCode();
return;
}
if (sub === 'git-refresh') { void this.refreshMercuryCodeGit(); return; }
return;
}
if (trimmed === '/mc') {
this.update({ exitEscArmed: false });
return;
}
if (trimmed === '/coding') {
this.update({ mode: this.state.mode === 'mercury-code' ? 'mercury-code' : 'coding' });
return;
}
if (trimmed === '/workspace' || trimmed === '/ws') {
if (this.state.mode === 'mercury-code') return;
this.update({ mode: this.state.workspace?.active ? 'workspace' : 'coding' });
return;
}
if (trimmed === '/ws up') {
this.moveWorkspaceSelection(-1);
return;
}
if (trimmed === '/ws down') {
this.moveWorkspaceSelection(1);
return;
}
if (trimmed === '/ws open-selected') {
this.toggleOrSelectWorkspaceNode();
return;
}
if (trimmed === '/ws exit' || trimmed === '/workspace exit' || trimmed === '/general') {
if (this.state.mode === 'mercury-code') return;
this.exitWorkspaceToChat();
return;
}
if (trimmed === '/ws close-file') {
this.closeWorkspaceFile();
return;
}
if (trimmed === '/ws collapse') {
this.collapseWorkspaceNode();
return;
}
if (trimmed === '/ws expand') {
this.expandWorkspaceNode();
return;
}
if (trimmed.startsWith('/ws scroll ')) {
const [deltaRaw, viewportRaw] = trimmed.slice(11).trim().split(/\s+/);
const delta = parseInt(deltaRaw, 10);
const viewportLines = parseInt(viewportRaw, 10);
if (!isNaN(delta)) this.scrollWorkspaceCode(delta, Number.isFinite(viewportLines) ? viewportLines : 1);
return;
}
if (trimmed === '/ws scroll-home') {
this.scrollWorkspaceCodeToBoundary('top');
return;
}
if (trimmed.startsWith('/ws scroll-end ')) {
const viewportLines = parseInt(trimmed.slice(15), 10);
this.scrollWorkspaceCodeToBoundary('bottom', Number.isFinite(viewportLines) ? viewportLines : 1);
return;
}
if (trimmed.startsWith('/ws focus ')) {
const area = trimmed.slice(9).trim() as 'explorer' | 'code' | 'git' | 'chat';
if (['explorer', 'code', 'git', 'chat'].includes(area)) this.setWorkspaceFocus(area);
return;
}
if (trimmed === '/ws toggle-chat') {
this.toggleWorkspaceChat();
return;
}
if (trimmed.startsWith('/ws chat-scroll ')) {
const delta = parseInt(trimmed.slice(16), 10);
if (!isNaN(delta)) this.scrollWorkspaceChat(delta);
return;
}
if (trimmed.startsWith('/ws chat-set ')) {
const distance = parseInt(trimmed.slice(13), 10);
if (Number.isFinite(distance)) this.setWorkspaceChatDistance(distance);
return;
}
if (trimmed === '/ws chat-home') {
this.setWorkspaceChatBoundary('top');
return;
}
if (trimmed === '/ws chat-end') {
this.setWorkspaceChatBoundary('bottom');
return;
}
if (trimmed === '/menu' || trimmed === '/m') {
if (this.state.mode === 'mercury-code') return;
this.update({ mode: 'menu' });
return;
}
if (trimmed === '/spotify' || trimmed === '/s') {
if (this.state.mode === 'mercury-code') return;
this.update({ mode: 'spotify' });
return;
}
if (trimmed === '/splash') {
if (this.state.mode === 'mercury-code') return;
this.update({ mode: 'splash' });
return;
}
if (trimmed === '/view balanced') {
this.update({ viewMode: 'balanced' });
return;
}
if (trimmed === '/view detailed') {
this.update({ viewMode: 'detailed' });
return;
}
if (trimmed === '/view toggle' || trimmed === '/view') {
this.update({ viewMode: this.state.viewMode === 'balanced' ? 'detailed' : 'balanced' });
return;
}
// Show last task's full step log (triggered by Ctrl+D or /log)
if (trimmed === '/log') {
const steps = this.state.toolSteps.length > 0 ? this.state.toolSteps : (this.state.lastStepLog ?? []);
if (steps.length > 0) {
const elapsed = this.state.lastStepLogElapsed;
const suffix = this.state.toolSteps.length > 0 ? ' (active)' : '';
const elapsedSec = elapsed != null ? ` · ${Math.round(elapsed / 1000)}s` : '';
const lines = steps.map((s) => {
const icon = s.status === 'done' ? '✓' : s.status === 'error' ? '✗' : '→';
const time = s.elapsed != null ? ` (${s.elapsed.toFixed(1)}s)` : '';
const result = s.result ? ` · ${s.result}` : '';
return `${icon} ${s.label}${time}${result}`;
});
const header = `── Step log (${steps.filter((s) => s.status === 'done').length}/${steps.length} done${elapsedSec}${suffix}) ──`;
const msg: ChatMessage = {
id: `log-${Date.now().toString(36)}`,
role: 'system',
content: `${header}\n${lines.join('\n')}`,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, msg]);
} else {
const msg: ChatMessage = {
id: `log-${Date.now().toString(36)}`,
role: 'system',
content: 'No step history available yet. Run a task first, then press Ctrl+D.',
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, msg]);
}
return;
}
// Clear stale tool steps from the previous task so the activity
// panel starts fresh for each new user message.
if (this.state.toolSteps.length > 0) {
this.update({ toolSteps: [] });
this.stepCount = 0;
}
onInput(trimmed);
};
// Reset mouse-report modes in case a previous run left the terminal
// stuck emitting mouse sequences (1000/1002/1003 + SGR 1006), and turn
// on bracketed paste so multi-line pastes arrive as one literal chunk
// (the stdin filter strips the ESC[200~/201~ markers; see
// MouseSequenceFilter). Turned off again by restoreTerminal() and the
// output wrapper's dispose().
try {
process.stdout.write(mouseTrackingSequences(false) + bracketedPasteSequences(true));
} catch {
// Not a TTY or write failed — nothing to reset.
}
this.tuiOutput?.dispose();
this.tuiOutput = new ResilientTuiOutput(process.stdout, process.stderr);
// Real terminal cursor on the input cell for IME (#41, #66); the
// vendored ink parks it after every frame. MERCURY_HW_CURSOR=0 opts out.
configureHardwareCursor();
this.warnIfInkUnpatched();
// Single mount. Every later UI update flows through useSyncExternalStore
// notifications — never inkInstance.rerender(), whose synchronous
// reconciler entry caused re-entrant commits and Yoga WASM corruption.
this.captureConsole();
this.inkInstance = render(
React.createElement(TuiApp, {
channel: this,
onInput: (text: string) => { this.inputHandler?.(text); },
onPermissionResolve: (value: string | boolean) => {
const shown = this.state.permissionPrompt;
if (shown?.id && this.resolvePrompt(shown.id, value)) return;
// No live resolver for what is on screen (stale state): clear it
// and surface whatever is queued next.
this.update({ permissionPrompt: this.promptQueue.shift() ?? null });
},
onExit: () => {
this.scheduleTuiExit();
},
onInterrupt: () => { this.interruptTurn(); },
spotifyClient: this.spotifyClient,
}),
{
exitOnCtrlC: false,
patchConsole: false,
// Rewrite only the changed part of each line (ink 8). Replaces the
// diff-render hunk Mercury carried on ink 5.
incrementalRendering: true,
stdin: (this.stdinProxy ?? process.stdin) as unknown as NodeJS.ReadStream,
stdout: this.tuiOutput as unknown as NodeJS.WriteStream,
},
);
// After the output wrapper had to shed writes, the screen no longer
// matches the renderer's baseline: clear() makes the next frame a full
// repaint, and the same-size 'resize' triggers it.
const output = this.tuiOutput;
const ink = this.inkInstance;
if (output) {
output.onResync = () => {
ink.clear();
output.emit('resize');
};
}
}
/**
* While the TUI owns the terminal nothing may print behind the renderer's
* back. The renderer redraws only the rows that changed and assumes the
* screen holds exactly what it last wrote; a stray console line (a library
* warning, say) shifts everything down, the next erase misses rows, and the
* "Processing" block stays frozen in the transcript. Console output goes to
* the logger instead (silent unless --verbose) until teardown.
*/
private captureConsole(): void {
/* eslint-disable no-console -- this is the console redirect itself */
if (this.restoreConsole) return;
const methods = ['log', 'info', 'warn', 'error', 'debug'] as const;
const original = methods.map((m) => [m, console[m]] as const);
for (const m of methods) {
console[m] = (...args: unknown[]) => {
const level = m === 'error' ? 'error' : m === 'warn' ? 'warn' : 'debug';
logger[level]({ console: m }, args.map((a) => (typeof a === 'string' ? a : inspect(a))).join(' '));
};
}
this.restoreConsole = () => {
for (const [m, fn] of original) console[m] = fn;
};
/* eslint-enable no-console */
}
private inkPatchWarned = false;
/**
* Stock ink ignores `<Static itemKey>`: the transcript silently stops
* rendering new messages after ~100 (and the Yoga crash class is live).
* The patch is applied by postinstall, which npm users never see fail —
* so say it once, in the transcript, with the one command that fixes it.
* Never aborts: a degraded TUI beats no TUI for a hotfix.
*/
private warnIfInkUnpatched(): void {
if (this.inkPatchWarned) return;
this.inkPatchWarned = true;
try {
const status = detectInkPatch();
if (status.patched) return;
const text = inkPatchWarning(status);
logger.warn({ missing: status.missing, inkBuildDir: status.inkBuildDir }, 'ink patch not applied');
this.trimAndSetMessages([
...this.state.chatMessages,
{ id: `ink-patch-${Date.now().toString(36)}`, role: 'system', content: text, timestamp: Date.now() },
]);
} catch (err) {
logger.debug({ err }, 'ink patch detection failed');
}
}
private stdinProxy: TtyStdinProxy | null = null;
/** Install the filtered-stdin proxy: Ink reads clean text; the mouse
* filter (always active) delivers wheel events for transcript scrolling
* and never lets raw sequences leak into the input. */
private installStdinProxy(): void {
if (this.stdinProxy) return;
const proxy = new TtyStdinProxy(process.stdin, new MouseSequenceFilter(
(ev) => this.dispatchMouseEvent(ev),
(s) => proxy.write(s),
));
this.stdinProxy = proxy;
}
/** Hard cap on rendered transcript messages held in TUI state. */
private static readonly MAX_CHAT_MESSAGES = 2000;
/**
* Byte budget for the rendered transcript. Sized to retain a full
* Mercury Code session without scrolling history out of reach: even a
* 75-step coding task with file echoes stays ~2MB now that per-message
* content is capped and the AI SDK no longer clones raw bodies per step.
*/
private static readonly MAX_CHAT_CHARS = 4 * 1024 * 1024;
/** Per-message cap: larger payloads are truncated with a notice. */
private static readonly MAX_MESSAGE_CHARS = 64 * 1024;
private trimAndSetMessages(messages: ChatMessage[], extra: Partial<TuiState> = {}): void {
// Transcript bounds: cap both message count and total retained chars.
// Dropping oldest keeps renders + heap flat while preserving the tail
// the user is actively reading. The WorkLedger/session stores preserve
// the full history elsewhere.
let trimmed = messages.length > CLIChannel.MAX_CHAT_MESSAGES
? messages.slice(-CLIChannel.MAX_CHAT_MESSAGES)
: messages;
// Per-message display cap: one multi-MB payload (a whole-file echo from
// a coding task) must never dominate the transcript heap. Full text is
// preserved in the session store; the TUI keeps the head + a notice.
trimmed = trimmed.map((msg) => msg.content.length > CLIChannel.MAX_MESSAGE_CHARS
? { ...msg, content: msg.content.slice(0, CLIChannel.MAX_MESSAGE_CHARS) + `\n\n[…display truncated at ${Math.round(CLIChannel.MAX_MESSAGE_CHARS / 1024)}KB — full content in session history]` }
: msg);
let total = 0;
for (const msg of trimmed) total += msg.content.length;
while (trimmed.length > 1 && total > CLIChannel.MAX_CHAT_CHARS) {
total -= trimmed[0].content.length;
trimmed = trimmed.slice(1);
}
if (trimmed.length !== messages.length) {
trimmed = trimmed.map((msg, i) => i === 0 && trimmed.length > 0
? { ...msg, content: `[…earlier transcript trimmed to keep Mercury responsive…]\n${msg.content}` }
: msg);
}
this.update({ chatMessages: trimmed, ...extra });
}
/**
* Show a file-change preview in the transcript (Mercury Code / coding
* surfaces): a bounded, syntax-highlighted excerpt of what the agent just
* wrote or edited. Formatted by utils/file-preview.ts. Skips silently
* when the identical preview is already the last message (tool retries).
*/
showFileChange(content: string): void {
// Mercury Code shows the change inside the tool's own transcript block.
if (!content || this.state.mode === 'mercury-code') return;
const last = this.state.chatMessages[this.state.chatMessages.length - 1];
if (last && last.role === 'system' && last.content === content) return;
const msg: ChatMessage = {
id: `file-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
role: 'system',
content,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, msg]);
}
async send(content: string, targetId?: string, _elapsedMs?: number): Promise<void> {
const msg: ChatMessage = {
id: Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
role: 'agent',
content,
timestamp: Date.now(),
};
// Bot transcripts (targetId `bot:<id>`, BOTS-ARCHITECTURE §3.3): route to
// the bot's own thread — live if it is the one on screen, else stored.
if (targetId?.startsWith('bot:')) {
this.appendBotMessage(targetId.slice(4), msg);
return;
}
// Clear any lingering heartbeat message when we send a real response.
let chat = this.state.chatMessages;
if (this.heartbeatMsgId) {
chat = chat.filter((m) => m.id !== this.heartbeatMsgId);
this.heartbeatMsgId = null;
}
// While a bot chat is open, main-agent traffic must not leak into the
// bot's thread: non-bot sends land in the parked main transcript.
if (this.activeBotId) {
// Parked main traffic is bounded by the same transcript cap as the
// visible transcript (review I1 — daemon-in-bot-chat memory growth).
this.mainTranscript = [
...(this.mainTranscript ?? []).slice(-CLIChannel.MAX_CHAT_MESSAGES + 1),
msg,
];
return;
}
this.trimAndSetMessages([...chat, msg], { isThinking: false, liveActivity: null });
}
/**
* Send or replace a heartbeat progress message. First call creates a new
* message; subsequent calls update it in place. This avoids stacking
* multiple "⏳ Working..." messages in the chat history.
*/
sendHeartbeat(content: string): void {
if (this.heartbeatMsgId) {
// Update existing heartbeat message in place.
this.updateMessage(this.heartbeatMsgId, content, { role: 'system' });
} else {
// First heartbeat — create the message.
const id = `heartbeat-${Date.now().toString(36)}`;
this.heartbeatMsgId = id;
const msg: ChatMessage = { id, role: 'system', content, timestamp: Date.now() };
this.trimAndSetMessages([...this.state.chatMessages, msg], { isThinking: true });
}
}
/** Clear the heartbeat message (called when processing completes). */
clearHeartbeat(): void {
if (this.heartbeatMsgId) {
// All state changes must go through update() — direct mutation here
// previously bypassed render notification.
const id = this.heartbeatMsgId;
this.heartbeatMsgId = null;
this.update({
chatMessages: this.state.chatMessages.filter((m) => m.id !== id),
isThinking: false,
});
} else {
this.rerender();
}
}
/**
* Durable system notice (provider fallback errors, switch announcements).
* Unlike the heartbeat, it RENDERS in Mercury Code (heartbeat rows are
* filtered out of the coding transcript) and it is NOT removed when the
* turn ends — the user must still see, after the response, that a provider
* failed and the task continued on another route.
*/
sendSystemNotice(content: string): void {
const msg: ChatMessage = {
id: `notice-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
role: 'system',
content,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, msg]);
}
/**
* Real-time tool event: called at TOOL EXECUTION START (from the AI SDK's
* onToolCallStart), not after the LLM step completes. The step shows as
* running with a live elapsed timer while the tool actually runs.
*/
sendToolEvent(toolName: string, args: Record<string, any>, callId: string): Promise<void> {
// File-change attribution: remember the path this file-tool call targets.
if (FILE_CHANGE_TOOLS.has(toolName) && typeof args?.path === 'string' && args.path) {
this.pendingTurnFiles.set(callId, args.path);
}
const label = formatToolStep(toolName, args);
// Reuse an existing running step for the same callId (e.g. duplicate start).
const existing = this.state.toolSteps.find((s) => s.callId === callId && s.status === 'running');
if (existing) {
return this.sendToolFeedback(toolName, args);
}
const step: ToolStep = {
id: `step-${Date.now()}-${this.stepCount}`,
toolName,
label,
status: 'running',
startedAt: Date.now(),
callId,
};
this.stepCount += 1;
this.stepStartTime = Date.now();
if (this.showsToolTranscript(toolName)) {
this.toolArgs.set(step.id, args ?? {});
this.cutStreamSegment();
}
// Cap the live step list: long coding sessions can run hundreds of
// tool calls; an unbounded array both bloats renders and memory.
const MAX_LIVE_STEPS = 60;
this.update({
toolSteps: [...this.state.toolSteps, step].slice(-MAX_LIVE_STEPS),
isThinking: true,
});
return Promise.resolve();
}
/** Mercury Code records finished tool calls as transcript blocks. */
private showsToolTranscript(toolName: string): boolean {
return this.state.mode === 'mercury-code' && isTranscriptTool(toolName);
}
/**
* Close the agent message being streamed at its current text, and start a
* new (not yet visible) segment for whatever streams next. Called when a
* tool starts: everything the model said so far precedes the tool's block.
*/
private cutStreamSegment(): void {
const seg = this.streamSegment;
if (!seg) return;
if (seg.started) {
const content = this.capStreamDisplay(seg.text.trimEnd(), 'response');
const closed = { id: seg.id, role: 'agent' as const, content, timestamp: Date.now(), streaming: false };
this.update({ chatMessages: this.state.chatMessages.map((m) => (m.id === seg.id ? closed : m)) });
}
this.streamSegment = { id: CLIChannel.newMessageId(), text: '', started: false, lastRender: 0 };
}
private static newMessageId(): string {
return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
}
/** Streaming display cap: the complete text still reaches the session store. */
private capStreamDisplay(text: string, what: 'stream' | 'response'): string {
if (text.length <= CLIChannel.MAX_MESSAGE_CHARS) return text;
const kb = Math.round(CLIChannel.MAX_MESSAGE_CHARS / 1024);
return text.slice(0, CLIChannel.MAX_MESSAGE_CHARS) + (what === 'stream'
? `\n\n[…stream display truncated at ${kb}KB — full response in transcript]`
: `\n\n[…response display truncated at ${kb}KB]`);
}
/**
* Real-time tool completion: pairs with sendToolEvent via callId so the
* exact step that started flips to done — even when several tools ran.
*/
completeToolEvent(toolName: string, result: unknown, isError: boolean, durationMs?: number, callId?: string): void {
const summary = formatToolResult(toolName, result);
let matched = false;
let matchedCallId: string | undefined;
let matchedStepId: string | undefined;
// Exact callId match first (parallel calls of the same tool), else the
// oldest running step of that tool.
const byCallId = callId != null && this.state.toolSteps.some((s) => s.status === 'running' && s.callId === callId);
const toolSteps = this.state.toolSteps.map((step) => {
if (!matched && step.status === 'running' && step.toolName === toolName && (!byCallId || step.callId === callId)) {
matched = true;
matchedCallId = step.callId;
matchedStepId = step.id;
return {
...step,
status: (isError ? 'error' : 'done') as 'done' | 'error',
elapsed: durationMs != null ? durationMs / 1000 : (step.startedAt ? (Date.now() - step.startedAt) / 1000 : 0),
result: summary || undefined,
};
}
return step;
});
const args = matchedStepId ? this.toolArgs.get(matchedStepId) : undefined;
if (matchedStepId) this.toolArgs.delete(matchedStepId);
if (args && this.showsToolTranscript(toolName)) {
const { block, full } = buildToolBlockDetail({ toolName, args, result, isError, cwd: this.state.mercuryCode?.cwd });
if (full) {
this.expandableTools.push({ block, full });
if (this.expandableTools.length > CLIChannel.MAX_EXPANDABLE_TOOLS) this.expandableTools.shift();
}
this.appendToolBlock(block, { toolSteps });
} else {
this.update({ toolSteps });
}
// Attribution commit: a file-tool call that finished successfully actually
// mutated the tree; a failed one did not (errors surface in the step list).
if (matchedCallId) {
const path = this.pendingTurnFiles.get(matchedCallId);
this.pendingTurnFiles.delete(matchedCallId);
if (!isError && path) this.committedTurnFiles.add(path);
}
}
/**
* ctrl+o: print the full output of the most recent collapsed tool block.
* Scrollback can't be re-rendered, so the expansion is appended as a new
* block; pressing again walks back to the previous collapsed block.
*/
expandLastToolOutput(): void {
const entry = this.expandableTools.pop();
if (!entry) {
this.sendSystemNotice('Nothing to expand — no collapsed tool output.');
return;
}
const { block, full } = entry;
this.appendToolBlock({
...block,
summary: `Full output · ${full.lines.length} line${full.lines.length === 1 ? '' : 's'}`,
body: full,
}, {});
}
/** Append a finished tool call to the transcript (parked while a bot chat is open). */
private appendToolBlock(tool: ToolBlock, extra: Partial<TuiState>): void {
const msg: ChatMessage = {
id: `tool-${CLIChannel.newMessageId()}`,
role: 'system',
content: `${tool.title}${tool.target ? `(${tool.target})` : ''} — ${tool.summary}`,
timestamp: Date.now(),
tool,
};
if (this.activeBotId) {
this.mainTranscript = [...(this.mainTranscript ?? []).slice(-CLIChannel.MAX_CHAT_MESSAGES + 1), msg];
this.update(extra);
return;
}
this.trimAndSetMessages([...this.state.chatMessages, msg], extra);
}
sendCompletion(elapsedMs: number, stepCount: number, meta?: CompletionMeta, outcome?: 'complete' | 'steps-paused', verificationNote?: string): void {
this.clearHeartbeat();
this.clearLiveActivity();
const secs = Math.floor(elapsedMs / 1000);
const mins = Math.floor(secs / 60);
const remSecs = secs % 60;
const timeStr = mins > 0 ? `${mins}m ${remSecs}s` : `${secs}s`;
const stepsStr = stepCount > 0 ? `${stepCount} step${stepCount !== 1 ? 's' : ''}` : '';
const parts = [stepsStr, timeStr].filter(Boolean).join(' · ');
// Completion contract: a paused task never wears the completion banner,
// and execute-mode work that changed nothing cannot claim "complete".
let content = outcome === 'steps-paused'
? STEPS_PAUSED_BANNER
: `Task complete · ${parts}`;
// File changes are SMART-CONDITIONAL, never repo-wide git status:
// - The list attributes ONLY files the turn's own file-tool calls
// (write/create/edit/delete) actually mutated — a general chat turn
// (question, review, planning) touches no files, so no file section,
// no diff rows, no "next steps" — the banner stays clean.
// - Pre-existing uncommitted changes in the repo are never attributed to
// this task (the old behavior listed all of them on every banner).
const canVerifyChanges = this.state.mode === 'mercury-code'
&& (this.state.programmingMode === 'execute' || this.state.programmingMode === 'auto')
&& this.state.mercuryCode?.git.branch !== 'no-git';
const fileChanges = canVerifyChanges && this.committedTurnFiles.size > 0
? this.collectMercuryCodeChanges([...this.committedTurnFiles])
: undefined;
if (content.startsWith('Task complete') && fileChanges && fileChanges.length === 0) {
content = NO_CHANGES_BANNER + (parts ? ` · ${parts}` : '');
}
// End-of-task summary — files first (the developer's top question), then
// what was done, then the next steps.
if (fileChanges && fileChanges.length > 0) {
const planSteps = (this.state.planProgress ?? []).filter((s) => s.status === 'done').map((s) => s.label);
const doneSteps = planSteps.length > 0
? planSteps
: [...new Set(this.state.toolSteps.filter((s) => s.status !== 'error').map((s) => s.label))];
content += `\n\n${buildTaskSummary({
fileChanges,
doneSteps,
verified: !!verificationNote,
uncommitted: (this.state.mercuryCode?.git.dirty ?? 0) > 0,
})}`;
if (verificationNote) content += `\n✓ Verified: ${verificationNote}`;
}
const msg: ChatMessage = {
id: `done-${Date.now().toString(36)}`,
role: 'system',
content,
timestamp: Date.now(),
completionMeta: meta,
// File paths are inlined at the top of the summary text (above);
// attaching them again here would duplicate the rows in the transcript.
fileChanges: undefined,
};
this.trimAndSetMessages([...this.state.chatMessages, msg], {
isThinking: false,
toolSteps: [],
planProgress: null,
lastStepLog: this.state.toolSteps.length > 0 ? [...this.state.toolSteps] : (this.state.lastStepLog ?? null),
lastStepLogElapsed: elapsedMs,
});
// "Did you know?" perk: a natural pause (task just finished, nothing
// pending). The picker's internal min-gap keeps it to a rare treat, never
// repeated, always in the system's own voice. Mercury Code has its own
// rotating tip row — the chat notice only fires in chat surfaces.
if (this.state.mode !== 'mercury-code') {
const tip = nextTip('chat');
if (tip) this.sendSystemNotice(`💡 Did you know? ${tip.tip}`);
}
}
/**
* Live "thinking" preview: the tail of the model's reasoning while it
* works, so a silent generation phase is never dead air. Pass null to
* clear (when text starts streaming or the stream ends).
*/
showThinkingPreview(preview: string | null): void {
if (this.state.thinkingPreview === preview) return;
this.update({ thinkingPreview: preview });
}
/**
* Replace the live plan checklist (from the update_plan tool). Validates
* defensively — malformed model output must never break the TUI.
*/
/** The checklist as the terminal shows it now (null: none). */
currentPlanProgress(): PlanStep[] | null {
return this.state.planProgress ? this.state.planProgress.map((s) => ({ ...s })) : null;
}
setPlanProgress(steps: unknown): void {
if (!Array.isArray(steps)) return;
const normalized: PlanStep[] = [];
for (const raw of steps.slice(0, 20)) {
const label = typeof (raw as any)?.label === 'string' ? (raw as any).label.trim() : '';
const status = (raw as any)?.status;
if (!label || (status !== 'pending' && status !== 'active' && status !== 'done')) continue;
if (normalized.some((s) => s.label === label)) continue;
normalized.push({ label: label.slice(0, 120), status });
}
if (normalized.length === 0) return;
// Guard against two "active" steps from sloppy model updates.
const activeIdx = normalized.findIndex((s) => s.status === 'active');
normalized.forEach((s, i) => { if (s.status === 'active' && i !== activeIdx) s.status = 'pending'; });
this.update({ planProgress: normalized });
}
/**
* Stats for file changes, scoped to the given paths when provided (per-turn
* attribution) — repo-wide git status is never shown on the banner. Deleted
* or modified tracked files come from numstat; untracked files count as new.
*/
private collectMercuryCodeChanges(paths?: string[]): FileChangeSummary[] {
const cwd = this.state.mercuryCode?.cwd;
if (!cwd) return [];
const scopeFilter = (filePath: string): boolean => !paths || paths.includes(filePath);
const changes = new Map<string, FileChangeSummary>();
try {
let output = '';
try {
output = execFileSync('git', ['diff', '--numstat', 'HEAD', '--', ...(paths ?? [])], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
} catch {
output = execFileSync('git', ['diff', '--numstat', '--', ...(paths ?? [])], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
}
for (const line of output.split('\n')) {
if (!line.trim()) continue;
const [addedRaw, removedRaw, ...pathParts] = line.split('\t');
const filePath = pathParts.join('\t');
if (!filePath || !scopeFilter(filePath)) continue;
changes.set(filePath, {
path: filePath,
added: addedRaw === '-' ? null : Number.parseInt(addedRaw, 10) || 0,
removed: removedRaw === '-' ? null : Number.parseInt(removedRaw, 10) || 0,
});
}
} catch {
if (!paths) return [];
// A scoped diff that fails still allows the untracked pass below.
}
try {
const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
for (const filePath of untracked.split('\n').filter(Boolean)) {
if (!scopeFilter(filePath)) continue;
if (changes.has(filePath)) continue;
try {
const data = fs.readFileSync(path.join(cwd, filePath));
const binary = data.includes(0);
const text = binary ? '' : data.toString('utf8');
const added = binary ? null : (text.length === 0 ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0));
changes.set(filePath, { path: filePath, added, removed: binary ? null : 0 });
} catch {
changes.set(filePath, { path: filePath, added: null, removed: null });
}
}
} catch {
// A tracked diff is still useful when untracked-file discovery fails.
if (!paths) return [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
}
return [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
}
async sendFile(filePath: string, _targetId?: string): Promise<void> {
const fs = await import('node:fs');
const path = await import('node:path');
const resolved = path.resolve(filePath);
let content = '';
if (!fs.existsSync(resolved)) {
content = `File not found: ${filePath}`;
} else {
const stat = fs.statSync(resolved);
const sizeStr = stat.size > 1024 * 1024
? `${(stat.size / (1024 * 1024)).toFixed(1)}MB`
: stat.size > 1024
? `${(stat.size / 1024).toFixed(1)}KB`
: `${stat.size}B`;
content = `path: ${resolved}\nsize: ${sizeStr}`;
}
const msg: ChatMessage = {
id: Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
role: 'agent',
content,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, msg]);
}
async sendToolFeedback(toolName: string, args: Record<string, any>): Promise<void> {
const label = formatToolStep(toolName, args);
const step: ToolStep = {
id: `step-${Date.now()}-${this.stepCount}`,
toolName,
label,
status: 'running',
startedAt: Date.now(),
};
this.stepCount += 1;
this.stepStartTime = Date.now();
logger.debug({ tool: toolName, args }, 'voice.tui step start');
// Cap the live step list: long coding sessions can run hundreds of
// tool calls; an unbounded array both bloats renders and memory.
const MAX_LIVE_STEPS = 60;
const nextSteps = [...this.state.toolSteps, step].slice(-MAX_LIVE_STEPS);
this.update({
toolSteps: nextSteps,
isThinking: true,
});
}
sendStepDone(toolName: string, result: unknown): void {
const summary = formatToolResult(toolName, result);
const toolSteps = this.state.toolSteps.map((step) => {
if (step.status === 'running') {
const elapsed = this.stepStartTime ? (Date.now() - this.stepStartTime) / 1000 : 0;
return { ...step, status: 'done' as const, elapsed, result: summary || undefined };
}
return step;
});
logger.debug({ tool: toolName, summary }, 'voice.tui step done');
this.update({ toolSteps });
}
async stream(content: AsyncIterable<string>, _targetId?: string): Promise<string> {
// While a bot chat is open, main-agent streaming must NEVER render into
// the bot's transcript (review D1): consume silently and park the full
// reply into the parked main transcript instead.
if (this.activeBotId) {
let parked = '';
for await (const chunk of content) parked += chunk;
this.mainTranscript = [
...(this.mainTranscript ?? []).slice(-CLIChannel.MAX_CHAT_MESSAGES + 1),
{ id: Date.now().toString(36) + Math.random().toString(36).slice(2, 6), role: 'agent', content: parked, timestamp: Date.now() },
];
return parked;
}
// The reply streams into a SEGMENT: one agent message. In Mercury Code a
// tool call starting mid-stream closes the segment (cutStreamSegment) and
// later text opens a new one, so text and tool blocks interleave in the
// order they happened. `full` stays the whole reply for the caller.
const segment = { id: CLIChannel.newMessageId(), text: '', started: false, lastRender: 0 };
this.streamSegment = segment;
let full = '';
this.clearHeartbeat();
this.setLiveActivity('Streaming response', 'generating answer');
const render = (seg: NonNullable<CLIChannel['streamSegment']>, now: number) => {
// Streaming display cap: an unbounded string re-rendered every 60ms
// makes each frame allocate a fresh multi-MB message object; a long
// code-mode task can then retain gigabytes. The complete text still
// reaches the session store via the final channel.send().
const streamedMessage = { id: seg.id, role: 'agent' as const, content: this.capStreamDisplay(seg.text, 'stream'), timestamp: now, streaming: true };
this.update({
chatMessages: seg.started
? this.state.chatMessages.map((message) => message.id === seg.id ? streamedMessage : message)
: [...this.state.chatMessages, streamedMessage],
isThinking: true,
});
seg.started = true;
seg.lastRender = now;
};
try {
for await (const chunk of content) {
full += chunk;
const seg = this.streamSegment ?? segment;
// A segment opens on its first visible text: step separators ("\n\n")
// arriving right after a tool call must not open an empty message.
seg.text = seg.started ? seg.text + chunk : (seg.text + chunk).replace(/^\s*\n/, '');
if (!seg.started && seg.text.trim() === '') continue;
const now = Date.now();
// Throttle streaming re-renders to ~60ms. At 16ms the live Yoga
// tree was being recomputed on nearly every token, which — combined
// with markdown re-parsing of the full accumulated buffer each
// render — caused the visible "vibration"/flicker during generation.
// 60ms is fast enough to feel live while keeping each frame's layout
// stable.
if (!seg.started || now - seg.lastRender >= 60) render(seg, now);
}
} catch (err) {
const seg = this.streamSegment ?? segment;
this.streamSegment = null;
logger.warn({ err, partialLen: full.length }, 'CLI stream interrupted, saving partial text');
this.clearLiveActivity();
if (seg.text.trim().length > 0) {
const interruptedMessage = { id: seg.id, role: 'agent' as const, content: seg.text + '\n\n⚠ Stream was interrupted. Partial response shown above.', timestamp: Date.now(), streaming: false };
this.update({
chatMessages: seg.started
? this.state.chatMessages.map((message) => message.id === seg.id ? interruptedMessage : message)
: [...this.state.chatMessages, interruptedMessage],
isThinking: false,
});
} else {
this.update({
chatMessages: [...this.state.chatMessages, { id: seg.id, role: 'agent', content: full.length > 0 ? '⚠ Stream was interrupted. Partial response shown above.' : '⚠ Stream was interrupted before any response was generated.', timestamp: Date.now(), streaming: false }],
isThinking: false,
});
}
return full;
}
const seg = this.streamSegment ?? segment;
this.streamSegment = null;
if (seg.text.trim().length > 0) {
const finalMessage = { id: seg.id, role: 'agent' as const, content: this.capStreamDisplay(seg.text, 'response'), timestamp: Date.now(), streaming: false };
this.trimAndSetMessages(
seg.started
? this.state.chatMessages.map((message) => message.id === seg.id ? finalMessage : message)
: [...this.state.chatMessages, finalMessage],
{ isThinking: false, liveActivity: null },
);
} else {
// Nothing visible arrived in this segment (the model returned nothing,
// or the reply ended on a tool call): render no empty message.
this.update({ isThinking: false, liveActivity: null });
}
return full;
}
async typing(_targetId?: string): Promise<void> {
this.update({ isThinking: true });
}
showPrompt(): void {}
async withMenu<T>(runner: (select: (title: string, options: Array<{ value: string; label: string }>) => Promise<string>) => Promise<T>): Promise<T | undefined> {
this.menuDepth += 1;
const { selectWithArrowKeys } = await import('../utils/arrow-select.js');
this.menuAbortController = new AbortController();
try {
return await runner((title, options) => selectWithArrowKeys(title, options, {
signal: this.menuAbortController?.signal,
}));
} catch (error) {
if (error instanceof Error && error.name === 'ArrowSelectCancelledError') {
return undefined;
}
throw error;
} finally {
this.menuDepth = Math.max(0, this.menuDepth - 1);
if (this.menuDepth === 0) {
this.menuAbortController = null;
}
this.restoreRawModeAfterMenu();
}
}
private closeActiveMenu(): void {
if (!this.menuAbortController?.signal.aborted) {
this.menuAbortController?.abort();
}
}
/**
* Register a prompt: its resolver lives in the map under a fresh id, and
* it is shown now or queued behind the prompt already on screen. The
* returned promise settles exactly once, whenever ITS prompt is answered.
*/
private enqueuePrompt<T>(
prompt: Omit<PermissionPromptState, 'id' | 'resolve'>,
map: (value: string | boolean) => T,
): Promise<T> {
return new Promise<T>((resolve) => {
const id = `prompt-${++this.promptSeq}`;
this.promptResolvers.set(id, (value) => resolve(map(value)));
const entry: PermissionPromptState = { ...prompt, id, resolve: (value) => { this.resolvePrompt(id, value); } };
if (this.state.permissionPrompt) {
this.promptQueue.push(entry);
} else {
this.update({ permissionPrompt: entry });
}
});
}
/**
* Settle the prompt with this id. Returns false when no such prompt is
* pending (already answered, or unknown). If it was the one on screen,
* the next queued prompt is shown; if it was queued, it is removed.
*/
resolvePrompt(id: string, value: string | boolean): boolean {
const resolver = this.promptResolvers.get(id);
if (!resolver) return false;
this.promptResolvers.delete(id);
if (this.state.permissionPrompt?.id === id) {
this.update({ permissionPrompt: this.promptQueue.shift() ?? null });
} else {
this.promptQueue = this.promptQueue.filter((p) => p.id !== id);
}
resolver(value);
return true;
}
/** Ids of every unanswered prompt: the visible one first, then the queue. */
pendingPromptIds(): string[] {
const shown = this.state.permissionPrompt?.id;
const queued = this.promptQueue.map((p) => p.id).filter((id): id is string => typeof id === 'string');
return shown ? [shown, ...queued] : queued;
}
async prompt(question: string): Promise<string> {
return this.enqueuePrompt({ type: 'ask', message: question }, String);
}
/**
* The Ask Me / Allow All prompt for this session. `current` (the saved
* mode) is listed first, so Enter keeps it and ↓ Enter switches.
*/
async askPermissionMode(current?: PermissionMode): Promise<PermissionMode> {
if (!process.stdout.isTTY) return current ?? 'ask-me';
const options = [
{ value: 'allow-all', label: 'Allow All — auto-approve everything (scopes, commands, loop continuation)' },
{ value: 'ask-me', label: 'Ask Me — confirm before file writes, shell commands, and scope changes' },
];
if (current === 'ask-me') options.reverse();
return this.enqueuePrompt({
type: 'mode',
message: current
? `Permission mode for this session? (now: ${current === 'allow-all' ? 'Allow All' : 'Ask Me'} — Enter keeps it)`
: 'Choose how Mercury handles risky actions this session.',
options,
}, (val) => val as PermissionMode);
}
async askPermission(prompt: string): Promise<string> {
return this.enqueuePrompt({
type: 'ask',
message: prompt,
options: [
{ value: 'yes', label: 'Yes — approve once' },
{ value: 'always', label: 'Always — remember this permission' },
{ value: 'no', label: 'No — deny' },
],
}, String);
}
async presentChoicePrompt(question: string, options: Array<{ value: string; label: string }>): Promise<string> {
return this.enqueuePrompt({ type: 'choice', message: question, options }, String);
}
/**
* Resolve a pending choice prompt with a default value (timeout / dismissal).
* Time-weighted prompts use this so an unanswered question is answered FOR
* the user and the box disappears instead of lingering forever. With
* `id` the exact prompt is settled; without it, the OLDEST unanswered
* choice prompt (the one whose timer fired first) — visible or queued.
*/
resolveChoicePromptWithDefault(value: string, id?: string): void {
if (id) {
this.resolvePrompt(id, value);
return;
}
const target = [this.state.permissionPrompt, ...this.promptQueue]
.find((p): p is PermissionPromptState => Boolean(p && p.type === 'choice' && p.id && this.promptResolvers.has(p.id)));
if (target?.id) this.resolvePrompt(target.id, value);
}
async askToContinue(question: string, _targetId?: string): Promise<boolean> {
return this.enqueuePrompt({
type: 'continue',
message: question,
options: [
{ value: 'yes', label: 'Yes — continue' },
{ value: 'no', label: 'No — stop' },
],
}, (val) => {
const normalized = typeof val === 'string' ? val.trim().toLowerCase() : val;
return normalized === true || normalized === 'yes' || normalized === 'y';
});
}
/**
* Dismiss every pending prompt. Each promise still settles — with the
* prompt's "declined" answer — so no caller hangs on a box that is gone.
*/
clearPermissionPrompt(): void {
for (const id of this.pendingPromptIds()) {
const entry = this.state.permissionPrompt?.id === id ? this.state.permissionPrompt : this.promptQueue.find((p) => p.id === id);
this.resolvePrompt(id, CLIChannel.dismissedAnswer(entry));
}
this.promptQueue = [];
this.update({ permissionPrompt: null });
}
/** The answer a dismissed prompt reports (mirrors the TUI's Esc handling). */
private static dismissedAnswer(prompt: PermissionPromptState | null | undefined): string | boolean {
switch (prompt?.type) {
case 'mode': return 'ask-me';
case 'choice': return '';
case 'continue': return false;
default: return prompt?.options ? 'no' : '';
}
}
/** Status-bar note for a desktop plugin's activity (Optimus listening / working); null clears it. */
/** The permission mode shown on the bottom bar. */
setPermissionModeStatus(mode: PermissionMode): void {
if (this.state.permissionMode === mode) return;
this.update({ permissionMode: mode });
}
setDesktopActivity(text: string | null): void {
if (this.state.desktopActivity === text) return;
this.update({ desktopActivity: text });
}
setSkills(skills: SkillInfo[]): void {
this.update({ skills });
}
setProvider(name: string, model: string, badge?: string): void {
this.update({ provider: { name, model, badge } });
}
setCurrentSession(session: CurrentSessionInfo | null): void {
this.update({ currentSession: session });
}
setTokenInfo(used: number, budget: number, percentage: number): void {
this.update({ tokenInfo: { used, budget, percentage } });
}
setSaverMode(state: import('../core/saver-mode.js').SaverModeState, savedToday: number, savedLifetime: number): void {
if (state === 'off' && savedToday === 0 && savedLifetime === 0) {
// Keep null to preserve zero-impact UI when saver has never been touched.
this.update({ saverInfo: null });
return;
}
this.update({ saverInfo: { state, savedToday, savedLifetime } });
}
setWebInfo(enabled: boolean, port: number): void {
this.update({ web: { enabled, port } });
}
setSubAgents(agents: SubAgentInfo[]): void {
this.update({ subAgents: agents });
}
/**
* Push a real-time activity phase to the live feedback block. Called by the
* agent at execution time (provider call, tool start, streaming) — the TUI
* shows what is happening now, not just post-step results.
*/
setLiveActivity(phase: string, detail?: string): void {
const existing = this.state.liveActivity;
this.update({
liveActivity: {
phase,
detail,
stepsDone: existing?.stepsDone ?? 0,
startedAt: existing?.phase === phase && existing?.detail === detail
? existing.startedAt
: Date.now(),
},
isThinking: true,
});
}
/** Advance the live step counter (called when an AI SDK step completes). */
bumpLiveActivitySteps(): void {
const existing = this.state.liveActivity;
if (existing) this.update({ liveActivity: { ...existing, stepsDone: existing.stepsDone + 1 } });
}
/**
* Per-bot real-time activity: what a bot is doing RIGHT NOW, rendered as a
* live region inside its open thread (same spinner block the main chat
* gets). Events arrive from the bot activity bus (BotManager.onBotActivity).
* Mapping: turn-start → "Working on: <task>"; step/tool labels follow the
* actual work; tool finishes keep the last running label (less churn);
* 'thinking' carries the bot's live reasoning/reply tails and lands in
* botStreamTails so the open thread renders what it is thinking;
* turn-end clears the region (and the tails).
*/
setBotLiveActivity(botId: string, ev: { kind: 'turn-start' | 'step' | 'tool' | 'turn-end' | 'thinking'; label: string; detail?: string; status?: string; reasoningTail?: string; textTail?: string }): void {
const map = { ...this.state.botLiveActivity };
if (ev.kind === 'turn-end') {
if (!map[botId]) {
const tails = { ...this.state.botStreamTails };
if (!tails[botId]) return;
delete tails[botId];
this.update({ botStreamTails: tails });
return;
}
delete map[botId];
const tails = { ...this.state.botStreamTails };
delete tails[botId];
this.update({ botLiveActivity: map, botStreamTails: tails });
return;
}
if (ev.kind === 'thinking') {
// Skip when the tail hasn't changed — ink re-renders every update and
// the streaming cadence (300ms) must not paint identical frames.
const tails = { ...this.state.botStreamTails };
const prev = tails[botId];
if (prev && prev.reasoning === (ev.reasoningTail ?? '') && prev.text === (ev.textTail ?? '')) return;
tails[botId] = { reasoning: ev.reasoningTail ?? '', text: ev.textTail ?? '' };
this.update({ botStreamTails: tails });
return;
}
// A finished tool keeps its label until the next event — the region
// should not flicker to an intermediate state and back.
if (ev.kind === 'tool' && ev.status === 'done' && map[botId]) return;
const existing = map[botId];
map[botId] = {
phase: ev.kind === 'turn-start' ? 'Working' : ev.label,
detail: ev.kind === 'turn-start'
? ev.label.slice(0, 80)
: ev.status === 'error'
? `✗ ${ev.label}${ev.detail ? ` — ${ev.detail}` : ''}`
: undefined,
stepsDone: ev.kind === 'step' ? (existing?.stepsDone ?? 0) + 1 : (existing?.stepsDone ?? 0),
startedAt: existing?.startedAt ?? Date.now(),
};
// A fresh turn starts thinking anew — any leftover tail (missed turn-end,
// restart) must not bleed into the new turn's preview.
const staleTail = ev.kind === 'turn-start' && this.state.botStreamTails[botId];
if (staleTail) {
const tails = { ...this.state.botStreamTails };
delete tails[botId];
this.update({ botLiveActivity: map, botStreamTails: tails });
return;
}
this.update({ botLiveActivity: map });
}
/** Clear the live activity block (task finished or idle). */
clearLiveActivity(): void {
// Turn-end cleanup: clear the phase AND the thinking state together.
// In plain chat the final pushLiveActivity ('Finalizing response') sets
// isThinking, and no channel.send/sendCompletion follows (the response
// was already streamed; no banner for simple turns) — so the spinner
// survived the turn and rendered "Processing" forever while the agent
// was idle.
if (this.state.liveActivity || this.state.isThinking) {
this.update({ liveActivity: null, isThinking: false });
}
}
updateBackgroundTasks(tasks: BackgroundTaskInfo[]): void {
this.update({ backgroundTasks: tasks });
}
setSidebarSections(sections: SidebarSection[]): void {
this.update({ sidebarSections: sections });
}
setMode(mode: AppMode): void {
this.update({ mode });
}
/** Read-only snapshot of the current TUI state (for cross-module checks). */
getTuiState(): TuiState {
return this.state;
}
// ─── Mercury Code (`/code`) full-screen mode ─────────────────────────────
/**
* Enable or disable SGR mouse tracking. When enabled, the filtered stdin
* stream forwards parsed mouse events to `handler`; wheel scroll drives
* transcript scrollback in Mercury Code.
*/
setMouseEnabled(enabled: boolean, handler?: (ev: MouseEvent) => void): void {
this.mouseEnabled = enabled;
this.mouseHandler = enabled ? (handler ?? null) : null;
try {
process.stdout.write(mouseTrackingSequences(enabled));
} catch {
// Not a TTY or write failed — mouse stays off.
this.mouseEnabled = false;
this.mouseHandler = null;
}
this.update({ mercuryCode: this.state.mercuryCode ? { ...this.state.mercuryCode, mouse: enabled } : null });
}
isMouseEnabled(): boolean {
return this.mouseEnabled;
}
/** Internal: called by the filtered stdin stream on a parsed mouse event. */
private dispatchMouseEvent(ev: MouseEvent): void {
if (!this.mouseEnabled) return;
this.mouseHandler?.(ev);
}
/**
* Enter Mercury Code: full-screen coding TUI bound to `dir`.
* Switches to plan mode by default (analyze-first). The transcript prints
* into the terminal's native scrollback (<Static>), so scrolling and
* drag-selection are terminal-native: mouse reporting stays OFF — it would
* capture wheel/drag events and break both.
*/
enterMercuryCode(dir: string, version: string): { ok: boolean; message: string } {
const target = path.resolve(dir.replace(/^~(?=$|\/|\\)/, homedir()));
if (!fs.existsSync(target)) return { ok: false, message: `Directory does not exist: ${target}` };
if (!fs.statSync(target).isDirectory()) return { ok: false, message: `Not a directory: ${target}` };
// A bot chat must not survive a mode switch: a stranded activeBotId would
// park every later send into the hidden main transcript (invisible
// responses) and wrap nothing visibly. The typed /code path already
// exits the bot chat first — this covers every OTHER entry (the
// automatic coding hand-off, Esc flows).
if (this.activeBotId) this.exitBotChat();
const dirName = path.basename(target) || target;
this.exitEscArmed = false;
this.update({
mode: 'mercury-code',
mercuryCode: {
cwd: target,
dirName,
// Filled in asynchronously below: a blocking git read here stalled
// the first frame. An EMPTY branch means "not read yet" (the status
// bar hides the segment); 'no-git' is the settled "not a repo"
// answer, which also disables completion-time change stats.
git: { branch: '', ahead: 0, behind: 0, dirty: 0 },
mouse: false,
scrollOffset: 0,
exitConfirm: false,
},
projectContext: target,
version,
// AUTO is the default Mercury Code flow: plan and build in one pass,
// confirming with the user only for large/consequential changes.
programmingMode: 'auto',
exitEscArmed: false,
});
try {
process.stdout.write('\x1b[2J\x1b[H');
} catch { /* ignore */ }
// Graceful one-time notices (never blocking, never repeated): the
// /whatsnew hint when this boot is a fresh install or an update, and a
// throttled background update check. Entirely async and unref'd — a slow
// npm look-up must never stall the TUI.
void this.announceVersionNotices(version);
// Branch / ahead / behind / dirty for the status bar — off the hot path.
void this.refreshMercuryCodeGit();
return { ok: true, message: `Mercury Code active in ${dirName}` };
}
/**
* One-time, once-per-version notices on Mercury Code entry. Tests skip the
* network check (VITEST); the hint is persisted in update-state.json so it
* cannot repeat for the same version even across restarts.
*/
private async announceVersionNotices(version: string): Promise<void> {
if (process.env.VITEST || process.env.MERCURY_NO_UPDATE_CHECK === '1') return;
try {
const { shouldShowWhatsNewHint, markWhatsNewHintShown, getIgnoredUpdateVersion, shownMessageIds, rememberNotices } = await this.updateNoticeApi();
if (shouldShowWhatsNewHint(version)) {
markWhatsNewHintShown(version);
this.sendSystemNotice(`☿ Mercury v${version} is here. Type \`/whatsnew\` to see what's new.`);
}
// The signed update manifest decides "required" and carries messages;
// without it, the plain version look-up still offers updates.
const { serverUpdateStatus } = await import('../updates/status.js');
const { startupNotices } = await import('../updates/notices.js');
const status = await serverUpdateStatus({ current: version });
const out = startupNotices(status, getIgnoredUpdateVersion(), shownMessageIds());
rememberNotices(out.shown, status.latest?.version);
if (out.badge) this.setUpdateAvailable(out.badge);
for (const n of out.notices) this.sendSystemNotice(n);
} catch (err) {
logger.debug({ err }, 'announceVersionNotices failed (non-fatal)');
}
}
/** Latest version the user hasn't ignored (for /update ignore even when the check is throttled). */
setUpdateAvailable(latestVersion: string | null): void {
this.update({ updateAvailable: latestVersion });
}
/**
* Push the Mercury Code status-verb pool (agent's one-shot LLM refinement,
* or the keyword fallback when that failed). Empty lists are ignored — they
* would fall through to the static label anyway.
*/
setStatusVerbs(verbs: string[]): void {
if (!Array.isArray(verbs) || verbs.length === 0) return;
this.update({ statusVerbs: verbs });
}
exitMercuryCode(): void {
if (this.state.mercuryCode) {
this.setMouseEnabled(false);
}
this.exitEscArmed = false;
this.update({
mode: 'chat',
mercuryCode: null,
programmingMode: 'off',
projectContext: null,
planProgress: null,
exitEscArmed: false,
statusVerbs: null,
});
try {
process.stdout.write('\x1b[2J\x1b[H');
} catch { /* ignore */ }
}
/** Toggle the exit confirmation inline in Mercury Code. */
setMercuryCodeExitConfirm(show: boolean): void {
if (!this.state.mercuryCode) return;
this.update({ mercuryCode: { ...this.state.mercuryCode, exitConfirm: show } });
}
/** Adjust transcript scrollback (distance from bottom, clamped). */
scrollMercuryCode(deltaTowardTop: number): void {
const mc = this.state.mercuryCode;
if (!mc) return;
const next = Math.max(0, mc.scrollOffset + deltaTowardTop);
if (next !== mc.scrollOffset) {
this.update({ mercuryCode: { ...mc, scrollOffset: next } });
}
}
/** Snap transcript to live (bottom). */
scrollMercuryCodeToLive(): void {
const mc = this.state.mercuryCode;
if (!mc || mc.scrollOffset === 0) return;
this.update({ mercuryCode: { ...mc, scrollOffset: 0 } });
}
/** A git header refresh in flight (coalesces overlapping requests). */
private gitRefreshInFlight: Promise<void> | null = null;
/**
* Refresh the cached git header state from disk — asynchronously. The
* old `execSync` pair blocked the event loop for the whole `git status`
* (hundreds of ms on a large tree), freezing streaming and input every
* time Mercury Code entered or `/mc git-refresh` ran.
*/
refreshMercuryCodeGit(): Promise<void> {
if (this.gitRefreshInFlight) return this.gitRefreshInFlight;
const mc = this.state.mercuryCode;
if (!mc) return Promise.resolve();
const cwd = mc.cwd;
this.gitRefreshInFlight = this.readGitStateQuick(cwd)
.then((git) => {
const current = this.state.mercuryCode;
// The session may have left Mercury Code (or moved) meanwhile.
if (!current || current.cwd !== cwd) return;
if (
git.branch !== current.git.branch ||
git.ahead !== current.git.ahead ||
git.behind !== current.git.behind ||
git.dirty !== current.git.dirty
) {
this.update({ mercuryCode: { ...current, git } });
}
})
.catch((err) => logger.debug({ err }, 'git header refresh failed'))
.finally(() => { this.gitRefreshInFlight = null; });
return this.gitRefreshInFlight;
}
/** Header-sized git state (branch / ahead / behind / dirty count) via async execFile. */
private async readGitStateQuick(rootPath: string): Promise<MercuryCodeGitState> {
const state = await this.readGitStateAsync(rootPath);
if (state.branch === 'not-a-git-repo') return { branch: 'no-git', ahead: 0, behind: 0, dirty: 0 };
return { branch: state.branch, ahead: state.ahead, behind: state.behind, dirty: state.files.length };
}
setProgrammingStatus(mode: import('../core/programming-mode.js').ProgrammingModeState, projectContext: string | null): void {
this.update({ programmingMode: mode, projectContext });
}
openWorkspace(rawPath: string): { ok: boolean; message: string } {
const target = path.resolve(rawPath.replace(/^~(?=$|\/|\\)/, homedir()));
if (!fs.existsSync(target)) return { ok: false, message: `Workspace path does not exist: ${target}` };
if (!fs.statSync(target).isDirectory()) return { ok: false, message: `Workspace path is not a directory: ${target}` };
const workspace = this.buildWorkspaceState(target, undefined, 'Workspace opened');
this.update({ workspace, mode: 'workspace', projectContext: target });
return { ok: true, message: `Workspace opened: ${target}` };
}
refreshWorkspace(): void {
if (!this.state.workspace?.active) return;
const selectedPath = this.state.workspace.selectedPath ?? undefined;
const workspace = this.buildWorkspaceState(this.state.workspace.rootPath, selectedPath, 'Workspace refreshed');
this.update({ workspace });
}
/**
* Register provider callbacks the poller will sample on every tick.
* Called once at boot from index.ts. Each callback should be cheap
* (just a getter on already-in-memory state).
*/
setStatusProviders(providers: typeof this.statusProviders): void {
this.statusProviders = { ...this.statusProviders, ...providers };
}
/**
* Start the 2s status poller. Refreshes:
* - token budget bar (every tick)
* - saver mode state (every tick)
* - sub-agent counts (every tick)
* - background task counts (every tick)
* - workspace git state (every tick, async, only if workspace is active)
*
* Each section diff-checks its values before calling update() so
* idle ticks cause zero React re-renders.
*/
startStatusPoller(intervalMs = 2000): void {
this.stopStatusPoller();
this.statusPoller = setInterval(() => { void this.statusPollerTick(); }, intervalMs);
// Fire once immediately so the first paint is fresh.
void this.statusPollerTick();
}
stopStatusPoller(): void {
if (this.statusPoller) {
clearInterval(this.statusPoller);
this.statusPoller = null;
}
}
private async statusPollerTick(): Promise<void> {
// Re-entrancy guard: if a previous git read is still in flight we skip.
if (this.statusPollerBusy) return;
this.statusPollerBusy = true;
try {
const patch: Partial<TuiState> = {};
// 1. Token budget
if (this.statusProviders.tokens) {
const t = this.statusProviders.tokens();
const cur = this.state.tokenInfo;
if (!cur || cur.used !== t.used || cur.budget !== t.budget || cur.percentage !== t.percentage) {
patch.tokenInfo = { used: t.used, budget: t.budget, percentage: t.percentage };
}
}
// 2. Saver mode
if (this.statusProviders.saver) {
const s = this.statusProviders.saver();
const cur = this.state.saverInfo;
const shouldShow = !(s.state === 'off' && s.savedToday === 0 && s.savedLifetime === 0);
if (!shouldShow) {
if (cur !== null) patch.saverInfo = null;
} else if (!cur || cur.state !== s.state || cur.savedToday !== s.savedToday || cur.savedLifetime !== s.savedLifetime) {
patch.saverInfo = { state: s.state, savedToday: s.savedToday, savedLifetime: s.savedLifetime };
}
}
// 3. Sub-agents
if (this.statusProviders.subAgents) {
const agents = this.statusProviders.subAgents();
if (!shallowEqualSubAgents(this.state.subAgents, agents)) {
patch.subAgents = agents;
}
}
// 4. Background tasks
if (this.statusProviders.bgTasks) {
const tasks = this.statusProviders.bgTasks();
if (!shallowEqualBgTasks(this.state.backgroundTasks, tasks)) {
patch.backgroundTasks = tasks;
}
}
// 4b. Bot roster — drives /bots argument autocomplete (§3.2)
if (this.statusProviders.botRoster) {
const roster = this.statusProviders.botRoster();
const current = this.state.botRoster;
if (current.length !== roster.length || current.some((b, i) =>
b.id !== roster[i].id || b.name !== roster[i].name || b.state !== roster[i].state || b.needsYou !== roster[i].needsYou)) {
patch.botRoster = roster;
}
}
// 5. Workspace git state (async — branch/files/ahead/behind can
// change from outside Mercury, so we re-read every tick)
if (this.state.workspace?.active) {
const root = this.state.workspace.rootPath;
const fresh = await this.readGitStateAsync(root);
const cur = this.state.workspace;
if (
cur.branch !== fresh.branch ||
cur.ahead !== fresh.ahead ||
cur.behind !== fresh.behind ||
cur.stagedCount !== fresh.stagedCount ||
cur.unstagedCount !== fresh.unstagedCount ||
cur.gitFiles.length !== fresh.files.length
) {
patch.workspace = {
...cur,
branch: fresh.branch,
ahead: fresh.ahead,
behind: fresh.behind,
stagedCount: fresh.stagedCount,
unstagedCount: fresh.unstagedCount,
gitFiles: fresh.files,
};
}
}
// 6. Mercury Code header (branch / ahead / behind / dirty count).
// Async git read: execSync here blocks the event loop while the TUI
// is rendering (and mid-task), which stalls streaming + input.
if (this.state.mode === 'mercury-code' && this.state.mercuryCode) {
const mc = this.state.mercuryCode;
const asyncState = await this.readGitStateAsync(mc.cwd);
const fresh = {
branch: asyncState.branch,
ahead: asyncState.ahead,
behind: asyncState.behind,
dirty: asyncState.files.length,
};
if (
fresh.branch !== mc.git.branch ||
fresh.ahead !== mc.git.ahead ||
fresh.behind !== mc.git.behind ||
fresh.dirty !== mc.git.dirty
) {
patch.mercuryCode = { ...mc, git: fresh };
}
}
if (Object.keys(patch).length > 0) {
this.update(patch);
}
} catch {
// Polling should never crash the UI loop.
} finally {
this.statusPollerBusy = false;
}
}
stageWorkspaceFile(filePath: string): { ok: boolean; message: string } {
if (!this.state.workspace?.active) return { ok: false, message: 'No active workspace.' };
const root = this.state.workspace.rootPath;
try {
const rel = filePath === 'all' ? '.' : filePath;
execSync(`git add ${this.quoteArg(rel)}`, { cwd: root, stdio: 'pipe' });
this.refreshWorkspace();
return { ok: true, message: rel === '.' ? 'Staged all changes.' : `Staged: ${rel}` };
} catch (err: any) {
return { ok: false, message: `Stage failed: ${err?.message || String(err)}` };
}
}
undoWorkspaceFile(filePath: string): { ok: boolean; message: string } {
if (!this.state.workspace?.active) return { ok: false, message: 'No active workspace.' };
const root = this.state.workspace.rootPath;
try {
execSync(`git checkout -- ${this.quoteArg(filePath)}`, { cwd: root, stdio: 'pipe' });
this.refreshWorkspace();
return { ok: true, message: `Reverted: ${filePath}` };
} catch (err: any) {
return { ok: false, message: `Undo failed: ${err?.message || String(err)}` };
}
}
commitWorkspace(message: string): { ok: boolean; message: string } {
if (!this.state.workspace?.active) return { ok: false, message: 'No active workspace.' };
const root = this.state.workspace.rootPath;
if (!message.trim()) return { ok: false, message: 'Commit message is required.' };
const body = `${message.trim()}\n\nCo-authored-by: Mercury <[email protected]>`;
try {
execSync(`git commit -m ${this.quoteArg(body)}`, { cwd: root, stdio: 'pipe' });
this.refreshWorkspace();
return { ok: true, message: 'Commit created with Mercury co-author.' };
} catch (err: any) {
return { ok: false, message: `Commit failed: ${err?.message || String(err)}` };
}
}
getWorkspace(): WorkspaceState | null {
return this.state.workspace;
}
private quoteArg(v: string): string {
return `'${v.replace(/'/g, `'\\''`)}'`;
}
private moveWorkspaceSelection(delta: number): void {
if (!this.state.workspace?.active) return;
const next = Math.max(0, Math.min(this.state.workspace.nodes.length - 1, this.state.workspace.selectedIndex + delta));
const node = this.state.workspace.nodes[next];
this.update({
workspace: {
...this.state.workspace,
selectedIndex: next,
selectedPath: node?.path || null,
},
});
}
private toggleOrSelectWorkspaceNode(): void {
const ws = this.state.workspace;
if (!ws?.active) return;
const node = ws.nodes[ws.selectedIndex];
if (!node) return;
if (!node.isDir) {
const preview = this.readFilePreview(node.path);
this.update({
workspace: {
...ws,
selectedPath: node.path,
openedFilePath: node.path,
openedFilePreview: preview,
codeScrollOffset: 0,
focusArea: 'code',
lastAction: `Opened: ${path.basename(node.path)}`,
},
});
return;
}
const expanded = !node.expanded;
this.rebuildWorkspaceWithExpansion(node.path, expanded);
}
private collapseWorkspaceNode(): void {
const ws = this.state.workspace;
if (!ws?.active) return;
const node = ws.nodes[ws.selectedIndex];
if (!node?.isDir) return;
if (!node.expanded) return;
this.rebuildWorkspaceWithExpansion(node.path, false);
}
private expandWorkspaceNode(): void {
const ws = this.state.workspace;
if (!ws?.active) return;
const node = ws.nodes[ws.selectedIndex];
if (!node?.isDir) return;
if (node.expanded) return;
this.rebuildWorkspaceWithExpansion(node.path, true);
}
private rebuildWorkspaceWithExpansion(nodePath: string, expand: boolean): void {
const ws = this.state.workspace;
if (!ws) return;
const expandedSet = new Set(ws.nodes.filter((n) => n.isDir && n.expanded).map((n) => n.path));
if (expand) expandedSet.add(nodePath);
else expandedSet.delete(nodePath);
const workspace = this.buildWorkspaceState(ws.rootPath, ws.selectedPath || undefined, ws.lastAction, expandedSet);
this.update({ workspace });
}
private buildWorkspaceState(rootPath: string, selectedPath?: string, lastAction = '', preExpanded?: Set<string>): WorkspaceState {
const expanded = preExpanded || new Set<string>([rootPath]);
const nodes = this.buildTreeNodes(rootPath, expanded, 0);
const selectedIndex = Math.max(0, nodes.findIndex((n) => n.path === selectedPath));
const selectedNode = nodes[selectedIndex] || nodes[0] || null;
const { files, branch, stagedCount, unstagedCount, ahead, behind } = this.readGitState(rootPath);
return {
active: true,
rootPath,
nodes,
selectedIndex,
selectedPath: selectedNode?.path || null,
openedFilePath: this.state.workspace?.openedFilePath || null,
openedFilePreview: this.state.workspace?.openedFilePreview || [],
gitFiles: files,
stagedCount,
unstagedCount,
branch,
ahead,
behind,
lastAction,
codeScrollOffset: this.state.workspace?.codeScrollOffset ?? 0,
focusArea: this.state.workspace?.focusArea ?? 'explorer',
chatCollapsed: this.state.workspace?.chatCollapsed ?? false,
chatScrollOffset: this.state.workspace?.chatScrollOffset ?? 0,
rightPanel: this.state.workspace?.rightPanel ?? 'chat',
};
}
closeWorkspaceFile(): void {
const ws = this.state.workspace;
if (!ws?.active) return;
this.update({ workspace: { ...ws, openedFilePath: null, openedFilePreview: [], codeScrollOffset: 0, focusArea: 'explorer', lastAction: 'Closed file preview' } });
}
scrollWorkspaceCode(delta: number, viewportLines = 1): void {
const ws = this.state.workspace;
if (!ws?.active || !ws.openedFilePreview.length) return;
const maxOffset = Math.max(0, ws.openedFilePreview.length - Math.max(1, viewportLines));
const next = Math.max(0, Math.min(maxOffset, ws.codeScrollOffset + delta));
if (next !== ws.codeScrollOffset) {
this.update({ workspace: { ...ws, codeScrollOffset: next } });
}
}
private scrollWorkspaceCodeToBoundary(boundary: 'top' | 'bottom', viewportLines = 1): void {
const ws = this.state.workspace;
if (!ws?.active || !ws.openedFilePreview.length) return;
const codeScrollOffset = boundary === 'top'
? 0
: Math.max(0, ws.openedFilePreview.length - Math.max(1, viewportLines));
this.update({ workspace: { ...ws, codeScrollOffset } });
}
setWorkspaceFocus(area: 'explorer' | 'code' | 'git' | 'chat'): void {
const ws = this.state.workspace;
if (!ws?.active) return;
// When focusing git or chat, also switch the right panel
const rightPanel = area === 'git' ? 'git' : area === 'chat' ? 'chat' : ws.rightPanel;
this.update({ workspace: { ...ws, focusArea: area, rightPanel } });
}
toggleWorkspaceChat(): void {
const ws = this.state.workspace;
if (!ws?.active) return;
// Toggle right panel between chat and git
const rightPanel = ws.rightPanel === 'chat' ? 'git' : 'chat';
const focusArea = rightPanel === 'chat' ? 'chat' : ws.focusArea === 'chat' ? 'explorer' : ws.focusArea;
this.update({ workspace: { ...ws, rightPanel, focusArea } });
}
scrollWorkspaceChat(delta: number): void {
const ws = this.state.workspace;
if (!ws?.active) return;
const next = Math.max(0, ws.chatScrollOffset + delta);
if (next !== ws.chatScrollOffset) {
this.update({ workspace: { ...ws, chatScrollOffset: next } });
}
}
private setWorkspaceChatBoundary(boundary: 'top' | 'bottom'): void {
const ws = this.state.workspace;
if (!ws?.active) return;
this.update({
workspace: {
...ws,
chatScrollOffset: boundary === 'top' ? Number.MAX_SAFE_INTEGER : 0,
},
});
}
private setWorkspaceChatDistance(distance: number): void {
const ws = this.state.workspace;
if (!ws?.active) return;
const chatScrollOffset = Math.max(0, distance);
if (chatScrollOffset !== ws.chatScrollOffset) {
this.update({ workspace: { ...ws, chatScrollOffset } });
}
}
private exitWorkspaceToChat(): void {
const ws = this.state.workspace;
const nextWorkspace = ws ? { ...ws, active: false, focusArea: 'explorer' as const, codeScrollOffset: 0, chatCollapsed: false, chatScrollOffset: 0, rightPanel: 'chat' as const, lastAction: 'Exited workspace mode' } : null;
this.update({
mode: 'chat',
workspace: nextWorkspace,
programmingMode: 'off',
projectContext: null,
});
}
private readFilePreview(filePath: string): string[] {
try {
const raw = fs.readFileSync(filePath, 'utf-8');
return raw.replace(/\r\n?/g, '\n').split('\n').slice(0, 500);
} catch {
return ['(Unable to read file preview)'];
}
}
private buildTreeNodes(dir: string, expanded: Set<string>, depth: number): WorkspaceTreeNode[] {
const nodes: WorkspaceTreeNode[] = [];
const id = `${dir}:${depth}`;
const isExpanded = expanded.has(dir);
nodes.push({ id, name: depth === 0 ? path.basename(dir) || dir : path.basename(dir), path: dir, depth, isDir: true, expanded: isExpanded });
if (!isExpanded) return nodes;
let entries: fs.Dirent[] = [];
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
return nodes;
}
const sorted = entries
.filter((e) => e.name !== '.git' && e.name !== 'node_modules')
.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
for (const entry of sorted.slice(0, 200)) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
nodes.push(...this.buildTreeNodes(full, expanded, depth + 1));
} else {
nodes.push({ id: `${full}:${depth + 1}`, name: entry.name, path: full, depth: depth + 1, isDir: false });
}
}
return nodes;
}
private readGitState(rootPath: string): { files: WorkspaceGitFile[]; branch: string; stagedCount: number; unstagedCount: number; ahead: number; behind: number } {
try {
const branch = execSync('git branch --show-current', { cwd: rootPath, stdio: 'pipe' }).toString().trim() || 'detached';
const out = execSync('git status --porcelain=v1 --branch', { cwd: rootPath, stdio: 'pipe' }).toString();
return this.parseGitOutput(branch, out);
} catch {
return { files: [], branch: 'not-a-git-repo', stagedCount: 0, unstagedCount: 0, ahead: 0, behind: 0 };
}
}
private parseGitOutput(branch: string, statusOut: string): { files: WorkspaceGitFile[]; branch: string; stagedCount: number; unstagedCount: number; ahead: number; behind: number } {
const lines = statusOut.split('\n');
let ahead = 0;
let behind = 0;
const header = lines[0] || '';
const aheadMatch = header.match(/ahead (\d+)/);
const behindMatch = header.match(/behind (\d+)/);
if (aheadMatch) ahead = parseInt(aheadMatch[1], 10);
if (behindMatch) behind = parseInt(behindMatch[1], 10);
const files: WorkspaceGitFile[] = lines
.slice(1)
.map((line) => line.trimEnd())
.filter(Boolean)
.map((line) => {
const x = line[0] || ' ';
const y = line[1] || ' ';
const rel = line.slice(3).trim();
const staged = x !== ' ' && x !== '?';
const status = `${x}${y}`.trim() || '??';
return { path: rel, staged, status };
});
const stagedCount = files.filter((f) => f.staged).length;
const unstagedCount = files.length - stagedCount;
return { files, branch, stagedCount, unstagedCount, ahead, behind };
}
private execAsync(cmd: string, args: string[], cwd: string, timeoutMs = 1500): Promise<string> {
return new Promise((resolve, reject) => {
execFile(cmd, args, { cwd, timeout: timeoutMs, maxBuffer: 1024 * 512 }, (err, stdout) => {
if (err) reject(err);
else resolve(stdout.toString());
});
});
}
private async readGitStateAsync(rootPath: string): Promise<{ files: WorkspaceGitFile[]; branch: string; stagedCount: number; unstagedCount: number; ahead: number; behind: number }> {
try {
const [branchOut, statusOut] = await Promise.all([
this.execAsync('git', ['branch', '--show-current'], rootPath),
this.execAsync('git', ['status', '--porcelain=v1', '--branch'], rootPath),
]);
const branch = branchOut.trim() || 'detached';
return this.parseGitOutput(branch, statusOut);
} catch {
return { files: [], branch: 'not-a-git-repo', stagedCount: 0, unstagedCount: 0, ahead: 0, behind: 0 };
}
}
initSplash(agentName: string, version: string): void {
this.update({ agentName, version, mode: 'splash' });
}
sendUserMessage(content: string): void {
// New turn → reset file-change attribution (the buffer is per-turn).
this.pendingTurnFiles.clear();
this.committedTurnFiles.clear();
const userMsg: ChatMessage = {
id: Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
role: 'user',
content,
timestamp: Date.now(),
};
this.trimAndSetMessages([...this.state.chatMessages, userMsg]);
this.emit({
id: userMsg.id,
channelId: 'cli',
channelType: 'cli',
senderId: 'owner',
content,
timestamp: userMsg.timestamp,
});
}
}