@lotagate/cli 0.1.20 → 0.1.22

package/dist/presentation/tui/ink/tui-bridge.d.ts

@@ -0,0 +1,195 @@
+import type { Attachment } from '../../../domain/session/attachment.js';
+import type { ExecutionPlan } from '../../../domain/orchestration/task.js';
+import type { ChatUsage } from '../../../ports/chat-model.js';
+import type { FileChangeDiff } from '../../../domain/filesystem/file-change-diff.js';
+import type { ExtensionScope } from '../../../domain/extensions/extension-scope.js';
+import type { SubagentMode, SubagentStatus } from '../../../domain/orchestration/subagent.js';
+import type { SubagentHandoff } from '../../../domain/orchestration/subagent.js';
+import type { SubagentLastAction, SubagentLifecycleEvent } from '../../../ports/subagent-lifecycle.js';
+import type { CliActionKind } from '../../../application/orchestration/cli-turn-events.js';
+export type TuiMessageKind = 'user' | 'assistant' | 'command' | 'notice' | 'error' | 'diff' | 'activity' | 'subagent';
+export type TuiActivityState = 'pending' | 'running' | 'completed' | 'failed';
+export interface TuiMessage {
+    id: string;
+    kind: TuiMessageKind;
+    content: string;
+    attachments?: readonly Attachment[];
+    fileChange?: FileChangeDiff;
+    activity?: {
+        label: string;
+        state: TuiActivityState;
+        startedAt: number;
+        elapsedMs?: number;
+        toolName?: string;
+        kind?: CliActionKind;
+    };
+    subagent?: TuiSubagent;
+}
+export interface TuiSubagent {
+    readonly id: string;
+    readonly displayName: string;
+    readonly task: string;
+    readonly mode: SubagentMode;
+    readonly model: string;
+    readonly status: SubagentStatus;
+    readonly background: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly durationMs?: number;
+    readonly summary?: string;
+    readonly lastAction?: SubagentLastAction;
+    readonly handoff?: SubagentHandoff;
+}
+export interface TuiWelcome {
+    version: string;
+    cwd: string;
+    model: string | null;
+    profile: string | null;
+    trusted: boolean;
+}
+export interface TuiContextUsage {
+    usedTokens: number;
+    contextWindow?: number;
+}
+export interface TuiChoice {
+    value: string;
+    label: string;
+    description?: string;
+    kind?: 'file' | 'directory';
+}
+export type TuiModal = {
+    kind: 'trust';
+} | {
+    kind: 'plan';
+    plan: ExecutionPlan;
+} | {
+    kind: 'approval';
+    toolName: string;
+    detail?: string;
+} | {
+    kind: 'subagent';
+    subagent: TuiSubagent;
+} | {
+    kind: 'choice';
+    title: string;
+    choices: readonly TuiChoice[];
+    currentValue?: string;
+    detail?: string;
+} | {
+    kind: 'secret';
+    label: string;
+};
+export interface TuiViewState {
+    ready: boolean;
+    runActive: boolean;
+    welcome?: TuiWelcome | undefined;
+    messages: readonly TuiMessage[];
+    subagents: readonly TuiSubagent[];
+    status?: string | undefined;
+    footerNotice?: string | undefined;
+    activityStartedAt?: number | undefined;
+    elapsedMs?: number | undefined;
+    usage?: ChatUsage | undefined;
+    contextUsage?: TuiContextUsage | undefined;
+    pendingAttachments: readonly Attachment[];
+    fileSuggestions: readonly TuiChoice[];
+    modal?: TuiModal | undefined;
+    clearBlockedUntil?: number | undefined;
+    actionDetails: boolean;
+}
+type Listener = () => void;
+export declare class InkTuiBridge {
+    private readonly listeners;
+    private readonly initializationNotices;
+    private state;
+    private resolveModal;
+    private readonly exitResolvers;
+    private submitHandler;
+    private imagePasteHandler;
+    private textPasteHandler;
+    private clearAttachmentsHandler;
+    private interruptHandler;
+    private cancelHandler;
+    private sequence;
+    private noticeTimer;
+    private assistantFlushTimer;
+    private pendingAssistant;
+    private assistantSegmentPending;
+    private readonly pendingActivityTimers;
+    snapshot(): TuiViewState;
+    subscribe(listener: Listener): () => void;
+    setSubmitHandler(handler: (value: string) => Promise<void>): void;
+    setImagePasteHandler(handler: () => Promise<void>): void;
+    setTextPasteHandler(handler: () => Promise<string | undefined>): void;
+    setClearAttachmentsHandler(handler: () => void): void;
+    setInterruptHandler(handler: () => void): void;
+    setCancelHandler(handler: () => void): void;
+    submit(value: string): Promise<void>;
+    pasteImage(): Promise<void>;
+    pasteText(): Promise<string | undefined>;
+    interrupt(): void;
+    cancel(): void;
+    clearAttachments(): void;
+    setReady(): void;
+    setRunActive(runActive: boolean): void;
+    setWelcome(welcome: TuiWelcome): void;
+    setPendingAttachments(attachments: readonly Attachment[]): void;
+    setContextUsage(contextUsage: TuiContextUsage | undefined): void;
+    setFileSuggestions(fileSuggestions: readonly TuiChoice[]): void;
+    toggleActionDetails(): boolean;
+    clearTranscript(): void;
+    private exitCode;
+    requestExit(code?: number): void;
+    waitForExit(): Promise<number>;
+    userPrompt(content: string, attachments?: readonly Attachment[]): void;
+    command(content: string): void;
+    commandOutput(content: string): void;
+    transcriptNotice(content: string, notify?: boolean): void;
+    initializationNotice(key: string, content: string): void;
+    fileChange(change: FileChangeDiff): void;
+    notice(content: string): void;
+    dispose(): void;
+    error(content: string): void;
+    subagentLifecycle(event: SubagentLifecycleEvent): void;
+    startToolActivity(key: string, label: string, metadata?: {
+        toolName?: string;
+        kind?: CliActionKind;
+    }): {
+        complete: (isError: boolean) => void;
+    };
+    toolActivityStarted(key: string, label: string, metadata?: {
+        toolName?: string;
+        kind?: CliActionKind;
+    }): void;
+    toolActivityCompleted(key: string, isError: boolean): void;
+    status(label: string): void;
+    activity(label: string, elapsedMs: number, usage?: ChatUsage): void;
+    clearActivity(): void;
+    complete(elapsedMs: number, usage?: ChatUsage): void;
+    failed(): void;
+    cancelled(): void;
+    beginAssistant(): void;
+    /** Starts a new assistant segment after a host-owned action or approval boundary. */
+    assistantActionBoundary(): void;
+    assistantDelta(content: string): void;
+    finishAssistant(): void;
+    confirmTrust(): Promise<boolean>;
+    confirmPlan(plan: ExecutionPlan): Promise<boolean>;
+    confirmTool(toolName: string, detail?: string): Promise<boolean>;
+    openSubagentDetails(id: string): void;
+    closeSubagentDetails(): void;
+    selectModel(title: string, choices: readonly TuiChoice[], currentValue?: string): Promise<string | undefined>;
+    selectScope(title: string): Promise<ExtensionScope | undefined>;
+    requestSecret(label: string): Promise<string | undefined>;
+    resolveActiveModal(value: boolean | string | undefined): void;
+    private request;
+    private selectChoice;
+    private append;
+    private message;
+    private updateActivity;
+    private completeToolActivity;
+    private clearPendingActivityTimer;
+    private update;
+    private flushAssistant;
+}
+export {};

package/dist/presentation/tui/ink/tui-bridge.js

@@ -0,0 +1,289 @@
+import { RESOURCE_LIMITS } from '../../../domain/runtime/resource-limits.js';
+export class InkTuiBridge {
+    listeners = new Set();
+    initializationNotices = new Map();
+    state = { ready: false, runActive: false, messages: [], subagents: [], pendingAttachments: [], fileSuggestions: [], actionDetails: false };
+    resolveModal;
+    exitResolvers = new Set();
+    submitHandler;
+    imagePasteHandler;
+    textPasteHandler;
+    clearAttachmentsHandler;
+    interruptHandler;
+    cancelHandler;
+    sequence = 0;
+    noticeTimer;
+    assistantFlushTimer;
+    pendingAssistant;
+    assistantSegmentPending = false;
+    pendingActivityTimers = new Map();
+    snapshot() { return this.state; }
+    subscribe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+    setSubmitHandler(handler) { this.submitHandler = handler; }
+    setImagePasteHandler(handler) { this.imagePasteHandler = handler; }
+    setTextPasteHandler(handler) { this.textPasteHandler = handler; }
+    setClearAttachmentsHandler(handler) { this.clearAttachmentsHandler = handler; }
+    setInterruptHandler(handler) { this.interruptHandler = handler; }
+    setCancelHandler(handler) { this.cancelHandler = handler; }
+    async submit(value) { await this.submitHandler?.(value); }
+    async pasteImage() { await this.imagePasteHandler?.(); }
+    async pasteText() { return this.textPasteHandler?.(); }
+    interrupt() { this.interruptHandler?.(); }
+    cancel() {
+        this.cancelHandler?.();
+        this.resolveActiveModal(undefined);
+        this.update({ clearBlockedUntil: Date.now() + 1500 });
+    }
+    clearAttachments() { this.clearAttachmentsHandler?.(); }
+    setReady() { this.update({ ready: true }); }
+    setRunActive(runActive) { this.update({ runActive }); }
+    setWelcome(welcome) { this.update({ welcome }); }
+    setPendingAttachments(attachments) { this.update({ pendingAttachments: attachments }); }
+    setContextUsage(contextUsage) { this.update({ contextUsage }); }
+    setFileSuggestions(fileSuggestions) { this.update({ fileSuggestions }); }
+    toggleActionDetails() { const actionDetails = !this.state.actionDetails; this.update({ actionDetails }); return actionDetails; }
+    clearTranscript() { this.initializationNotices.clear(); this.update({ messages: [], subagents: [] }); }
+    exitCode;
+    requestExit(code = 0) { this.exitCode ??= code; for (const resolve of this.exitResolvers)
+        resolve(this.exitCode); this.exitResolvers.clear(); }
+    waitForExit() { return this.exitCode === undefined ? new Promise((resolve) => { this.exitResolvers.add(resolve); }) : Promise.resolve(this.exitCode); }
+    userPrompt(content, attachments = []) { this.append('user', content, attachments); }
+    command(content) { this.append('command', content); }
+    commandOutput(content) { this.append('notice', content); }
+    transcriptNotice(content, notify = true) { this.append('notice', content, undefined, undefined, undefined, undefined, notify); }
+    initializationNotice(key, content) {
+        if (this.initializationNotices.get(key) === content)
+            return;
+        this.initializationNotices.set(key, content);
+        this.transcriptNotice(content);
+    }
+    fileChange(change) { this.append('diff', change.path, undefined, change); }
+    notice(content) {
+        if (this.noticeTimer !== undefined)
+            clearTimeout(this.noticeTimer);
+        this.update({ footerNotice: content });
+        this.noticeTimer = setTimeout(() => {
+            this.noticeTimer = undefined;
+            this.update({ footerNotice: undefined });
+        }, 4000);
+    }
+    dispose() {
+        if (this.noticeTimer !== undefined)
+            clearTimeout(this.noticeTimer);
+        if (this.assistantFlushTimer !== undefined)
+            clearImmediate(this.assistantFlushTimer);
+        for (const timer of this.pendingActivityTimers.values())
+            clearImmediate(timer);
+        this.pendingActivityTimers.clear();
+        this.noticeTimer = undefined;
+        this.assistantFlushTimer = undefined;
+        this.resolveActiveModal(undefined);
+        this.initializationNotices.clear();
+        this.listeners.clear();
+    }
+    error(content) { this.append('error', content); }
+    subagentLifecycle(event) {
+        const deferRender = this.state.modal?.kind === 'subagent';
+        const existing = this.state.subagents.find((subagent) => subagent.id === event.id);
+        const subagent = {
+            id: event.id,
+            displayName: event.displayName,
+            task: event.task,
+            mode: event.mode,
+            model: event.model,
+            status: event.status,
+            background: event.background,
+            createdAt: existing?.createdAt ?? event.timestamp,
+            updatedAt: event.timestamp,
+            ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+            ...(event.summary === undefined ? {} : { summary: event.summary }),
+            ...(event.lastAction === undefined ? (existing?.lastAction === undefined ? {} : { lastAction: existing.lastAction }) : { lastAction: event.lastAction }),
+            ...(event.handoff === undefined ? (existing?.handoff === undefined ? {} : { handoff: existing.handoff }) : { handoff: event.handoff }),
+        };
+        const subagents = existing === undefined
+            ? [...this.state.subagents, subagent]
+            : this.state.subagents.map((candidate) => candidate.id === event.id ? subagent : candidate);
+        this.update({ subagents }, !deferRender);
+        if (event.type === 'created' && !this.state.messages.some((message) => message.kind === 'subagent' && message.subagent?.id === event.id)) {
+            this.append('subagent', event.id, undefined, undefined, undefined, subagent, !deferRender);
+        }
+        if ((event.type === 'completed' || event.type === 'failed' || event.type === 'cancelled') && event.summary !== undefined) {
+            this.transcriptNotice(`Agent ${event.displayName} ${event.status} · ${event.summary}`, !deferRender);
+        }
+    }
+    startToolActivity(key, label, metadata) {
+        const existing = this.state.messages.find((message) => message.kind === 'activity' && (message.activity?.state === 'pending' || message.activity?.state === 'running') && message.content === key);
+        let id = existing?.id;
+        if (existing === undefined) {
+            const created = this.message('activity', key, undefined, undefined, { label, state: 'running', startedAt: Date.now(), ...metadata });
+            id = created.id;
+            this.update({ messages: [...this.state.messages, created] });
+        }
+        else {
+            this.clearPendingActivityTimer(key);
+            this.updateActivity(existing.id, label, 'running', metadata);
+        }
+        return { complete: (isError) => this.completeToolActivity(id, isError) };
+    }
+    toolActivityStarted(key, label, metadata) {
+        const existing = this.state.messages.find((message) => message.kind === 'activity' && message.content === key && (message.activity?.state === 'pending' || message.activity?.state === 'running'));
+        if (existing !== undefined) {
+            this.updateActivity(existing.id, label, existing.activity?.state === 'pending' ? 'pending' : 'running', metadata);
+            return;
+        }
+        const created = this.message('activity', key, undefined, undefined, { label, state: 'pending', startedAt: Date.now(), ...metadata });
+        this.update({ messages: [...this.state.messages, created] });
+        const timer = setImmediate(() => {
+            this.pendingActivityTimers.delete(key);
+            const pending = this.state.messages.find((message) => message.kind === 'activity' && message.content === key && message.activity?.state === 'pending');
+            if (pending !== undefined)
+                this.updateActivity(pending.id, label, 'running', metadata);
+        });
+        this.pendingActivityTimers.set(key, timer);
+    }
+    toolActivityCompleted(key, isError) {
+        this.clearPendingActivityTimer(key);
+        const message = this.state.messages.find((candidate) => candidate.kind === 'activity' && candidate.content === key && (candidate.activity?.state === 'pending' || candidate.activity?.state === 'running'));
+        if (message !== undefined)
+            this.completeToolActivity(message.id, isError);
+    }
+    status(label) { this.update({ status: label, activityStartedAt: Date.now(), elapsedMs: undefined, usage: undefined }); }
+    activity(label, elapsedMs, usage) { this.update({ status: label, ...(this.state.activityStartedAt === undefined ? { activityStartedAt: Date.now() - elapsedMs } : {}), elapsedMs, ...(usage === undefined ? {} : { usage }) }); }
+    clearActivity() { this.update({ status: undefined, activityStartedAt: undefined, elapsedMs: undefined, usage: undefined }); }
+    complete(elapsedMs, usage) { this.update({ status: 'Done', elapsedMs, ...(usage === undefined ? {} : { usage }) }); }
+    failed() { this.update({ status: 'Failed', elapsedMs: undefined, usage: undefined }); }
+    cancelled() { this.update({ status: 'Cancelled', elapsedMs: undefined, usage: undefined }); }
+    beginAssistant() { this.flushAssistant(); this.assistantSegmentPending = false; this.append('assistant', ''); }
+    /** Starts a new assistant segment after a host-owned action or approval boundary. */
+    assistantActionBoundary() { this.flushAssistant(); this.assistantSegmentPending = true; }
+    assistantDelta(content) {
+        if (this.assistantSegmentPending) {
+            this.assistantSegmentPending = false;
+            this.append('assistant', content);
+            return;
+        }
+        const last = this.state.messages.at(-1);
+        if (last?.kind !== 'assistant') {
+            this.flushAssistant();
+            this.append('assistant', content);
+            return;
+        }
+        const pending = this.pendingAssistant;
+        this.pendingAssistant = { id: last.id, content: `${pending?.id === last.id ? pending.content : last.content}${content}` };
+        if (this.assistantFlushTimer === undefined)
+            this.assistantFlushTimer = setImmediate(() => { this.assistantFlushTimer = undefined; this.flushAssistant(); });
+    }
+    finishAssistant() { this.flushAssistant(); this.assistantSegmentPending = false; }
+    confirmTrust() { return this.request({ kind: 'trust' }).then((value) => value === true); }
+    confirmPlan(plan) { return this.request({ kind: 'plan', plan }).then((value) => value === true); }
+    confirmTool(toolName, detail) {
+        return this.request({ kind: 'approval', toolName, ...(detail === undefined ? {} : { detail }) }).then((value) => value === 'allow' || value === true);
+    }
+    openSubagentDetails(id) {
+        if (this.state.modal !== undefined)
+            return;
+        const subagent = this.state.subagents.find((candidate) => candidate.id === id);
+        if (subagent !== undefined)
+            this.update({ modal: { kind: 'subagent', subagent } });
+    }
+    closeSubagentDetails() {
+        if (this.state.modal?.kind === 'subagent')
+            this.update({ modal: undefined });
+    }
+    selectModel(title, choices, currentValue) {
+        return this.selectChoice(title, choices, currentValue);
+    }
+    selectScope(title) {
+        return this.selectChoice(title, [
+            { value: 'user', label: 'User', description: 'Available across your projects' },
+            { value: 'project', label: 'Project', description: 'Stored in the trusted project' },
+        ]).then((value) => value === 'user' || value === 'project' ? value : undefined);
+    }
+    requestSecret(label) { return this.request({ kind: 'secret', label }).then((value) => typeof value === 'string' ? value : undefined); }
+    resolveActiveModal(value) {
+        const resolve = this.resolveModal;
+        if (resolve === undefined)
+            return;
+        this.resolveModal = undefined;
+        this.update({ modal: undefined });
+        resolve?.(value);
+    }
+    request(modal) {
+        if (this.resolveModal !== undefined)
+            throw new Error('A TUI decision is already active.');
+        this.update({ modal });
+        return new Promise((resolve) => { this.resolveModal = resolve; });
+    }
+    selectChoice(title, choices, currentValue) {
+        return this.request({ kind: 'choice', title, choices, ...(currentValue === undefined ? {} : { currentValue }) }).then((value) => typeof value === 'string' ? value : undefined);
+    }
+    append(kind, content, attachments, fileChange, activity, subagent, notify = true) {
+        this.update({ messages: retainTranscriptMessages([...this.state.messages, this.message(kind, content, attachments, fileChange, activity, subagent)]) }, notify);
+    }
+    message(kind, content, attachments, fileChange, activity, subagent) {
+        return {
+            id: `tui-${++this.sequence}`,
+            kind,
+            content,
+            ...(attachments === undefined || attachments.length === 0 ? {} : { attachments }),
+            ...(fileChange === undefined ? {} : { fileChange }),
+            ...(activity === undefined ? {} : { activity }),
+            ...(subagent === undefined ? {} : { subagent }),
+        };
+    }
+    updateActivity(id, label, state, metadata) {
+        const messages = this.state.messages.map((message) => message.id === id && message.activity !== undefined
+            ? { ...message, content: message.content, activity: { ...message.activity, label, state, ...metadata } }
+            : message);
+        this.update({ messages });
+    }
+    completeToolActivity(id, isError) {
+        const message = this.state.messages.find((candidate) => candidate.id === id && candidate.activity !== undefined);
+        if (message?.activity === undefined || (message.activity.state !== 'pending' && message.activity.state !== 'running'))
+            return;
+        this.update({ messages: this.state.messages.map((candidate) => candidate.id === id && candidate.activity !== undefined
+                ? { ...candidate, activity: { ...candidate.activity, state: isError ? 'failed' : 'completed', elapsedMs: Date.now() - candidate.activity.startedAt } }
+                : candidate) });
+    }
+    clearPendingActivityTimer(key) {
+        const timer = this.pendingActivityTimers.get(key);
+        if (timer === undefined)
+            return;
+        clearImmediate(timer);
+        this.pendingActivityTimers.delete(key);
+    }
+    update(patch, notify = true) {
+        this.state = { ...this.state, ...patch };
+        if (!notify)
+            return;
+        for (const listener of this.listeners)
+            listener();
+    }
+    flushAssistant() {
+        if (this.assistantFlushTimer !== undefined) {
+            clearImmediate(this.assistantFlushTimer);
+            this.assistantFlushTimer = undefined;
+        }
+        const pending = this.pendingAssistant;
+        if (pending === undefined)
+            return;
+        this.pendingAssistant = undefined;
+        const index = this.state.messages.findIndex((message) => message.id === pending.id);
+        if (index < 0)
+            return;
+        const messages = [...this.state.messages];
+        const current = messages[index];
+        if (current === undefined || current.kind !== 'assistant')
+            return;
+        messages[index] = { ...current, content: pending.content };
+        this.update({ messages });
+    }
+}
+function retainTranscriptMessages(messages) {
+    if (messages.length <= RESOURCE_LIMITS.tuiTranscriptMessages)
+        return messages;
+    const active = messages.filter((message) => message.activity?.state === 'pending' || message.activity?.state === 'running' || message.subagent?.status === 'queued' || message.subagent?.status === 'running');
+    const recent = messages.slice(-RESOURCE_LIMITS.tuiTranscriptMessages);
+    const retained = [...active, ...recent.filter((message) => !active.some((candidate) => candidate.id === message.id))];
+    return retained.slice(-RESOURCE_LIMITS.tuiTranscriptMessages);
+}

package/dist/presentation/tui/terminal-capabilities.d.ts

@@ -0,0 +1,15 @@
+import type { Readable, Writable } from 'node:stream';
+export interface TerminalOutput extends Writable {
+    isTTY?: boolean;
+    columns?: number;
+    rows?: number;
+}
+export interface TerminalCapabilities {
+    isInteractive: boolean;
+    colorEnabled: boolean;
+    unicodeEnabled: boolean;
+    width: number;
+}
+export declare function detectTerminalCapabilities(input: Readable & {
+    isTTY?: boolean;
+}, output: TerminalOutput, env?: Readonly<Record<string, string | undefined>>): TerminalCapabilities;

package/dist/presentation/tui/terminal-capabilities.js

@@ -0,0 +1,7 @@
+export function detectTerminalCapabilities(input, output, env = process.env) {
+    const isInteractive = input.isTTY === true && output.isTTY === true;
+    const colorEnabled = isInteractive && env['NO_COLOR'] === undefined && env['TERM'] !== 'dumb';
+    const unicodeEnabled = env['LOTAGATE_ASCII'] !== '1';
+    const width = typeof output.columns === 'number' && output.columns > 0 ? output.columns : 80;
+    return { isInteractive, colorEnabled, unicodeEnabled, width };
+}

package/dist/presentation/tui/terminal-mouse.d.ts

@@ -0,0 +1,5 @@
+export type MouseWheelDirection = 'up' | 'down';
+/** Returns the wheel direction for an SGR mouse event, if the event is a wheel event. */
+export declare function parseMouseWheel(input: string): MouseWheelDirection | undefined;
+/** Identifies mouse escape sequences so they cannot be inserted into the prompt draft. */
+export declare function isMouseSequence(input: string): boolean;

package/dist/presentation/tui/terminal-mouse.js

@@ -0,0 +1,19 @@
+const ESC = String.fromCharCode(27);
+const SGR_MOUSE_SEQUENCE = /^\[<(\d+);(\d+);(\d+)([mM])$/u;
+/** Returns the wheel direction for an SGR mouse event, if the event is a wheel event. */
+export function parseMouseWheel(input) {
+    const match = SGR_MOUSE_SEQUENCE.exec(stripEscape(input));
+    if (match === null)
+        return undefined;
+    const button = Number(match[1]);
+    if ((button & 64) === 0)
+        return undefined;
+    return (button & 1) === 0 ? 'up' : 'down';
+}
+/** Identifies mouse escape sequences so they cannot be inserted into the prompt draft. */
+export function isMouseSequence(input) {
+    return /^\[<[0-9;]+[mM]$/u.test(stripEscape(input));
+}
+function stripEscape(input) {
+    return input.startsWith(ESC) ? input.slice(1) : input;
+}

package/dist/presentation/tui/terminal-screen.d.ts

@@ -0,0 +1,10 @@
+import type { TerminalOutput } from './terminal-capabilities.js';
+/** Starts the interactive application at the top of a clean terminal screen. */
+export declare function clearTerminalScreen(output: TerminalOutput): void;
+/**
+ * Isolates the interactive application from the invoking shell's scrollback.
+ * The terminal restores the original screen after the TUI has unmounted.
+ */
+export declare function enterInteractiveScreen(output: TerminalOutput): void;
+/** Restores the shell screen that was active before the interactive TUI. */
+export declare function exitInteractiveScreen(output: TerminalOutput): void;

package/dist/presentation/tui/terminal-screen.js

@@ -0,0 +1,23 @@
+const CLEAR_SCREEN_AND_HOME = '\u001B[2J\u001B[H';
+const ENTER_ALTERNATE_SCREEN = '\u001B[?1049h';
+const EXIT_ALTERNATE_SCREEN = '\u001B[?1049l';
+const ENABLE_SGR_MOUSE = '\u001B[?1000h\u001B[?1006h';
+const DISABLE_SGR_MOUSE = '\u001B[?1006l\u001B[?1000l';
+/** Starts the interactive application at the top of a clean terminal screen. */
+export function clearTerminalScreen(output) {
+    output.write(CLEAR_SCREEN_AND_HOME);
+}
+/**
+ * Isolates the interactive application from the invoking shell's scrollback.
+ * The terminal restores the original screen after the TUI has unmounted.
+ */
+export function enterInteractiveScreen(output) {
+    output.write(ENTER_ALTERNATE_SCREEN);
+    clearTerminalScreen(output);
+    output.write(ENABLE_SGR_MOUSE);
+}
+/** Restores the shell screen that was active before the interactive TUI. */
+export function exitInteractiveScreen(output) {
+    output.write(DISABLE_SGR_MOUSE);
+    output.write(EXIT_ALTERNATE_SCREEN);
+}

package/dist/presentation/tui/tui-agent-event-runner.d.ts

@@ -0,0 +1,24 @@
+import type { PreparedCliAgent } from '../../application/agent/cli-agent-execution-service.js';
+import type { AgentRunTracker } from '../../application/agent/agent-run-tracker.js';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { ChatUsage } from '../../ports/chat-model.js';
+import type { InkTuiBridge } from './ink/tui-bridge.js';
+import type { CliAgentSessionStore } from '../../application/agent/agent-session-store.js';
+export interface TuiAgentEventRunnerOptions {
+    prepared: PreparedCliAgent;
+    input: string;
+    model: string;
+    sessionId?: string;
+    turnId?: string;
+    signal: AbortSignal;
+    agentSessionStore: CliAgentSessionStore;
+    tracker: AgentRunTracker;
+    runtime: CliRuntime;
+    renderer: InkTuiBridge;
+    startedAt: number;
+    getUsage: () => ChatUsage | undefined;
+    appendAssistantDelta: (content: string) => void;
+    hasResponse: () => boolean;
+}
+/** Owns the CLI projection of the Agent SDK event stream for interactive runs. */
+export declare function runTuiAgentEvents(options: TuiAgentEventRunnerOptions): Promise<void>;

package/dist/presentation/tui/tui-agent-event-runner.js

@@ -0,0 +1,69 @@
+import { CliTurnEventProjector } from '../../application/orchestration/cli-turn-event-projector.js';
+import { persistCliTurnEvent } from '../../application/orchestration/cli-turn-persistence.js';
+import { persistContextCompaction } from '../../application/agent/context-compaction-persistence.js';
+import { renderAgentInitialization } from './agent-initialization-renderer.js';
+import { throwIfAborted } from './tui-lifecycle-actions.js';
+import { agentLimitNotice, classifyAgentLimit } from '../../application/agent/agent-limit.js';
+/** Owns the CLI projection of the Agent SDK event stream for interactive runs. */
+export async function runTuiAgentEvents(options) {
+    const projector = new CliTurnEventProjector();
+    renderAgentInitialization(options.renderer, await options.prepared.agent.initialize());
+    if (options.sessionId !== undefined) {
+        const history = await options.runtime.sessionStore.readHistory(options.sessionId);
+        options.agentSessionStore.hydrate(options.sessionId, options.prepared.system, history.transcript, history.events, options.input);
+    }
+    for await (const event of options.prepared.run({ input: options.input, model: options.model, ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }), signal: options.signal })) {
+        throwIfAborted(options.signal);
+        options.tracker.observe(event);
+        for (const item of projector.observe(event)) {
+            if (options.sessionId !== undefined) {
+                try {
+                    await persistCliTurnEvent(options.runtime.sessionStore, options.sessionId, item, { ...(options.turnId === undefined ? {} : { turnId: options.turnId }) });
+                }
+                catch (error) {
+                    options.runtime.logger.warn('Unable to persist agent lifecycle event.', { eventType: item.type, reason: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            if (item.type === 'assistant.delta')
+                options.appendAssistantDelta(item.content);
+            if (item.type === 'assistant.segment.completed')
+                options.renderer.assistantActionBoundary();
+            if (item.type === 'action.approval_requested') {
+                options.renderer.assistantActionBoundary();
+                options.renderer.status('Waiting for approval');
+            }
+            if (item.type === 'action.started') {
+                options.renderer.assistantActionBoundary();
+                options.runtime.logger.info('Agent tool called.', { toolName: item.toolName, actionId: item.actionId });
+                if (item.toolName !== 'agent.spawn')
+                    options.renderer.toolActivityStarted(item.actionId, item.displayName, { toolName: item.toolName, kind: item.kind });
+            }
+            if (item.type === 'action.completed') {
+                options.runtime.logger.info('Agent tool completed.', { toolName: item.toolName, actionId: item.actionId, isError: item.isError });
+                options.renderer.toolActivityCompleted(item.actionId, item.isError);
+            }
+        }
+        if (event.type === 'context.compacted') {
+            if (options.sessionId !== undefined)
+                await persistContextCompaction(options.runtime, options.prepared, options.sessionId, event.metrics, options.turnId);
+            options.renderer.transcriptNotice('Context compacted automatically.');
+            options.renderer.activity('Thinking', Date.now() - options.startedAt, options.getUsage());
+        }
+        if (event.type === 'session.failed') {
+            const limitReason = classifyAgentLimit(event.error);
+            if (limitReason === undefined)
+                throw event.error;
+            options.tracker.markStuck();
+            if (options.sessionId !== undefined)
+                options.agentSessionStore.delete(options.sessionId);
+            const notice = agentLimitNotice(limitReason);
+            if (options.hasResponse())
+                options.renderer.notice(notice);
+            else
+                options.appendAssistantDelta(notice);
+            return;
+        }
+        if (event.type === 'session.completed' && !options.hasResponse())
+            options.appendAssistantDelta(event.content);
+    }
+}