@adhdev/daemon-core 0.8.34 → 0.8.36

package/src/cli-adapters/provider-cli-adapter.ts

@@ -1428,8 +1428,6 @@ export class ProviderCliAdapter implements CliAdapter {
             throw new Error(`${this.cliName} is awaiting confirmation before it can accept a prompt`);
         }
 
-        this.committedMessages.push({ role: 'user', content: text, timestamp: Date.now() });
-        this.syncMessageViews();
         this.isWaitingForResponse = true;
         this.responseBuffer = '';
         this.finishRetryCount = 0;
@@ -1458,6 +1456,13 @@ export class ProviderCliAdapter implements CliAdapter {
         const submitDelayMs = this.sendDelayMs + Math.min(2000, Math.max(0, estimatedLines - 1) * 350);
         const maxEchoWaitMs = submitDelayMs + Math.max(1500, Math.min(5000, estimatedLines * 500));
         const retryDelayMs = Math.max(350, Math.min(1500, Math.max(this.sendDelayMs, submitDelayMs)));
+        let didCommitUserTurn = false;
+        const commitUserTurn = () => {
+            if (didCommitUserTurn) return;
+            didCommitUserTurn = true;
+            this.committedMessages.push({ role: 'user', content: text, timestamp: Date.now() });
+            this.syncMessageViews();
+        };
         if (this.settleTimer) {
             clearTimeout(this.settleTimer);
             this.settleTimer = null;
@@ -1470,115 +1475,134 @@ export class ProviderCliAdapter implements CliAdapter {
                 if (this.isWaitingForResponse) this.finishResponse();
             }, this.timeouts.maxResponse);
         };
+        await new Promise<void>((resolve) => {
+            let resolved = false;
+            const resolveOnce = () => {
+                if (resolved) return;
+                resolved = true;
+                resolve();
+            };
 
-        const submit = () => {
-            if (!this.ptyProcess) return;
-            this.submitPendingUntil = 0;
-            this.recordTrace('submit_write', {
-                mode: 'submit_key',
-                sendKey: this.sendKey,
-                screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
-            });
-            this.ptyProcess.write(this.sendKey);
-            const retrySubmitIfStuck = (attempt: number) => {
-                this.submitRetryTimer = null;
-                if (!this.ptyProcess || !this.isWaitingForResponse || this.submitRetryUsed) return;
-                if (this.currentStatus === 'waiting_approval') return;
-                if ((this.responseBuffer || '').trim()) return;
+            const submit = () => {
+                if (!this.ptyProcess) {
+                    resolveOnce();
+                    return;
+                }
+                commitUserTurn();
+                this.submitPendingUntil = 0;
                 const screenText = this.terminalScreen.getText();
-                if (!promptLikelyVisible(screenText, normalizedPromptSnippet)) return;
-                if (/Esc to interrupt|Do you want to proceed|This command requires approval|Allow Codex to|Approve and run now|Always approve this session|Running…|Running\.\.\./i.test(screenText)) return;
-                this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
-                LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt ${attempt})`);
                 this.recordTrace('submit_write', {
-                    mode: 'submit_retry',
-                    attempt,
+                    mode: 'submit_key',
                     sendKey: this.sendKey,
                     screenText: summarizeCliTraceText(screenText, 500),
                 });
-                this.ptyProcess.write(this.sendKey);
-                if (attempt >= 3) {
-                    this.submitRetryUsed = true;
-                    return;
-                }
-                this.submitRetryTimer = setTimeout(() => retrySubmitIfStuck(attempt + 1), retryDelayMs);
+                this.ptyProcess!.write(this.sendKey);
+                const retrySubmitIfStuck = (attempt: number) => {
+                    this.submitRetryTimer = null;
+                    if (!this.ptyProcess || !this.isWaitingForResponse || this.submitRetryUsed) return;
+                    if (this.currentStatus === 'waiting_approval') return;
+                    if ((this.responseBuffer || '').trim()) return;
+                    const screenText = this.terminalScreen.getText();
+                    if (!promptLikelyVisible(screenText, normalizedPromptSnippet)) return;
+                    if (/Esc to interrupt|Do you want to proceed|This command requires approval|Allow Codex to|Approve and run now|Always approve this session|Running…|Running\.\.\./i.test(screenText)) return;
+                    this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
+                    LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt ${attempt})`);
+                    this.recordTrace('submit_write', {
+                        mode: 'submit_retry',
+                        attempt,
+                        sendKey: this.sendKey,
+                        screenText: summarizeCliTraceText(screenText, 500),
+                    });
+                    this.ptyProcess.write(this.sendKey);
+                    if (attempt >= 3) {
+                        this.submitRetryUsed = true;
+                        return;
+                    }
+                    this.submitRetryTimer = setTimeout(() => retrySubmitIfStuck(attempt + 1), retryDelayMs);
+                };
+                this.submitRetryTimer = setTimeout(() => retrySubmitIfStuck(1), retryDelayMs);
+                startResponseTimeout();
+                resolveOnce();
             };
-            this.submitRetryTimer = setTimeout(() => retrySubmitIfStuck(1), retryDelayMs);
-            startResponseTimeout();
-        };
 
-        if (this.submitStrategy === 'immediate') {
-            this.submitPendingUntil = 0;
+            if (this.submitStrategy === 'immediate') {
+                commitUserTurn();
+                this.submitPendingUntil = 0;
+                this.recordTrace('submit_write', {
+                    mode: 'immediate',
+                    text: summarizeCliTraceText(text, 500),
+                    sendKey: this.sendKey,
+                    screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
+                });
+                this.ptyProcess!.write(text + this.sendKey);
+                this.submitRetryTimer = setTimeout(() => {
+                    this.submitRetryTimer = null;
+                    if (!this.ptyProcess || !this.isWaitingForResponse || this.submitRetryUsed) return;
+                    if (this.currentStatus === 'waiting_approval') return;
+                    if ((this.responseBuffer || '').trim()) return;
+                    const screenText = this.terminalScreen.getText();
+                    if (!promptLikelyVisible(screenText, normalizedPromptSnippet)) return;
+                    LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt 1)`);
+                    this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
+                    this.recordTrace('submit_write', {
+                        mode: 'immediate_retry',
+                        attempt: 1,
+                        sendKey: this.sendKey,
+                        screenText: summarizeCliTraceText(screenText, 500),
+                    });
+                    this.ptyProcess.write(this.sendKey);
+                    this.submitRetryUsed = true;
+                }, retryDelayMs);
+                startResponseTimeout();
+                resolveOnce();
+                return;
+            }
+
+            if (submitDelayMs > 0) {
+                this.submitPendingUntil = Date.now() + submitDelayMs;
+            }
+            this.ptyProcess!.write(text);
             this.recordTrace('submit_write', {
-                mode: 'immediate',
+                mode: 'type_then_submit',
                 text: summarizeCliTraceText(text, 500),
                 sendKey: this.sendKey,
                 screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
             });
-            this.ptyProcess.write(text + this.sendKey);
-            this.submitRetryTimer = setTimeout(() => {
-                this.submitRetryTimer = null;
-                if (!this.ptyProcess || !this.isWaitingForResponse || this.submitRetryUsed) return;
-                if (this.currentStatus === 'waiting_approval') return;
-                if ((this.responseBuffer || '').trim()) return;
+            const submitStartedAt = Date.now();
+            let lastNormalizedScreen = '';
+            let lastScreenChangeAt = submitStartedAt;
+            const waitForEchoAndSubmit = () => {
+                if (!this.ptyProcess) {
+                    resolveOnce();
+                    return;
+                }
+                const now = Date.now();
+                const elapsed = now - submitStartedAt;
                 const screenText = this.terminalScreen.getText();
-                if (!promptLikelyVisible(screenText, normalizedPromptSnippet)) return;
-                LOG.info('CLI', `[${this.cliType}] Retrying submit key for stuck prompt (attempt 1)`);
-                this.responseSettleIgnoreUntil = Date.now() + this.timeouts.outputSettle + 400;
-                this.recordTrace('submit_write', {
-                    mode: 'immediate_retry',
-                    attempt: 1,
-                    sendKey: this.sendKey,
-                    screenText: summarizeCliTraceText(screenText, 500),
-                });
-                this.ptyProcess.write(this.sendKey);
-                this.submitRetryUsed = true;
-            }, retryDelayMs);
-            startResponseTimeout();
-            return;
-        }
+                const normalizedScreen = normalizePromptText(screenText);
+                if (normalizedScreen !== lastNormalizedScreen) {
+                    lastNormalizedScreen = normalizedScreen;
+                    lastScreenChangeAt = now;
+                }
+                const echoVisible = !normalizedPromptSnippet || promptLikelyVisible(screenText, normalizedPromptSnippet);
 
-        if (submitDelayMs > 0) {
-            this.submitPendingUntil = Date.now() + submitDelayMs;
-        }
-        this.ptyProcess.write(text);
-        this.recordTrace('submit_write', {
-            mode: 'type_then_submit',
-            text: summarizeCliTraceText(text, 500),
-            sendKey: this.sendKey,
-            screenText: summarizeCliTraceText(this.terminalScreen.getText(), 500),
-        });
-        const submitStartedAt = Date.now();
-        let lastNormalizedScreen = '';
-        let lastScreenChangeAt = submitStartedAt;
-        const waitForEchoAndSubmit = () => {
-            if (!this.ptyProcess) return;
-            const now = Date.now();
-            const elapsed = now - submitStartedAt;
-            const screenText = this.terminalScreen.getText();
-            const normalizedScreen = normalizePromptText(screenText);
-            if (normalizedScreen !== lastNormalizedScreen) {
-                lastNormalizedScreen = normalizedScreen;
-                lastScreenChangeAt = now;
-            }
-            const echoVisible = !normalizedPromptSnippet || promptLikelyVisible(screenText, normalizedPromptSnippet);
+                if (echoVisible) {
+                    const screenSettled = (now - lastScreenChangeAt) >= 500;
+                    if (elapsed >= submitDelayMs && screenSettled) {
+                        submit();
+                        return;
+                    }
+                }
 
-            if (echoVisible) {
-                const screenSettled = (now - lastScreenChangeAt) >= 500;
-                if (elapsed >= submitDelayMs && screenSettled) {
+                if (elapsed >= maxEchoWaitMs) {
                     submit();
                     return;
                 }
-            }
 
-            if (elapsed >= maxEchoWaitMs) {
-                submit();
-                return;
-            }
-
-            setTimeout(waitForEchoAndSubmit, 50);
-        };
-        waitForEchoAndSubmit();
+                setTimeout(waitForEchoAndSubmit, 50);
+            };
+            waitForEchoAndSubmit();
+        });
     }
 
     getPartialResponse(): string {

package/src/cli-adapters/provider-cli-config.d.ts

@@ -0,0 +1,30 @@
+import type { CliProviderModule } from './provider-cli-shared.js';
+export interface ProviderResolutionMeta {
+    type: string;
+    name: string;
+    resolvedVersion: string | null;
+    resolvedOs: string | null;
+    providerDir: string | null;
+    scriptDir: string | null;
+    scriptsPath: string | null;
+    scriptsSource: string | null;
+    versionWarning: string | null;
+}
+export interface ResolvedCliAdapterConfig {
+    timeouts: {
+        ptyFlush: number;
+        dialogAccept: number;
+        approvalCooldown: number;
+        generatingIdle: number;
+        idleFinish: number;
+        maxResponse: number;
+        shutdownGrace: number;
+        outputSettle: number;
+    };
+    approvalKeys: Record<number, string>;
+    sendDelayMs: number;
+    sendKey: string;
+    submitStrategy: 'wait_for_echo' | 'immediate';
+    providerResolutionMeta: ProviderResolutionMeta;
+}
+export declare function resolveCliAdapterConfig(provider: CliProviderModule): ResolvedCliAdapterConfig;

package/src/cli-adapters/provider-cli-parse.d.ts

@@ -0,0 +1,42 @@
+import { type CliChatMessage, type CliScriptInput } from './provider-cli-shared.js';
+export interface TurnParseScope {
+    prompt: string;
+    startedAt: number;
+    bufferStart: number;
+    rawBufferStart: number;
+}
+export declare function hydrateCliParsedMessages(parsedMessages: any[], options: {
+    committedMessages: CliChatMessage[];
+    scope?: TurnParseScope | null;
+    lastOutputAt: number;
+    now?: number;
+}): any[];
+export declare function normalizeCliParsedMessages(parsedMessages: any[], options: {
+    committedMessages: CliChatMessage[];
+    scope?: TurnParseScope | null;
+    lastOutputAt: number;
+    now?: number;
+}): CliChatMessage[];
+export declare function buildCliParseInput(options: {
+    accumulatedBuffer: string;
+    accumulatedRawBuffer: string;
+    recentOutputBuffer: string;
+    terminalScreenText: string;
+    baseMessages: CliChatMessage[];
+    partialResponse: string;
+    scope?: TurnParseScope | null;
+    runtimeSettings: Record<string, any>;
+}): CliScriptInput;
+export declare function summarizeCliTraceText(text: string, max?: number): string;
+export declare function summarizeCliTraceMessages(messages: CliChatMessage[], limit?: number): {
+    role: string;
+    content: string;
+    timestamp?: number;
+}[];
+export declare function buildCliTraceParseSnapshot(options: {
+    accumulatedBuffer: string;
+    accumulatedRawBuffer: string;
+    responseBuffer: string;
+    partialResponse?: string;
+    scope?: TurnParseScope | null;
+}): Record<string, any>;

package/src/cli-adapters/provider-cli-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { PtySpawnOptions, PtyRuntimeTransport } from './pty-transport.js';
+import type { TerminalScreen } from './terminal-screen.js';
+import { type CliProviderModule } from './provider-cli-shared.js';
+export interface CliSpawnPlan {
+    binaryPath: string;
+    allArgs: string[];
+    shellCmd: string;
+    shellArgs: string[];
+    ptyOptions: PtySpawnOptions;
+    isWin: boolean;
+    useShell: boolean;
+}
+export declare function resolveCliSpawnPlan(options: {
+    provider: CliProviderModule;
+    runtimeSettings: Record<string, any>;
+    workingDir: string;
+    extraArgs: string[];
+}): CliSpawnPlan;
+export declare function buildCliLoginShellRetry(plan: Pick<CliSpawnPlan, 'binaryPath' | 'allArgs'>): {
+    shellCmd: string;
+    shellArgs: string[];
+};
+export declare function getCliSpawnErrorHint(message: string, shellCmd: string, isWin: boolean): string | null;
+export declare function respondToCliTerminalQueries(options: {
+    ptyProcess: PtyRuntimeTransport | null;
+    pendingTail: string;
+    data: string;
+    terminalScreen: TerminalScreen;
+}): string;

package/src/cli-adapters/provider-cli-shared.d.ts

@@ -0,0 +1,158 @@
+import type { ProviderResumeCapability } from '../providers/contracts.js';
+import { sanitizeSpawnEnv } from './spawn-env.js';
+export interface CliChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp?: number;
+    receivedAt?: number;
+    kind?: string;
+    id?: string;
+    index?: number;
+    meta?: Record<string, any>;
+    senderName?: string;
+}
+export interface CliSessionStatus {
+    status: 'idle' | 'generating' | 'waiting_approval' | 'error' | 'stopped' | 'starting';
+    messages: CliChatMessage[];
+    workingDir: string;
+    activeModal: {
+        message: string;
+        buttons: string[];
+    } | null;
+}
+export interface CliScripts {
+    parseOutput?: (input: CliScriptInput) => any;
+    detectStatus?: (input: CliStatusInput) => string | null;
+    parseApproval?: (input: CliApprovalInput) => {
+        message: string;
+        buttons: string[];
+    } | null;
+    resolveAction?: (data: any) => string;
+    [name: string]: ((input: any) => any) | undefined;
+}
+export interface CliScreenLine {
+    index: number;
+    fromTop: number;
+    fromBottom: number;
+    text: string;
+    trimmed: string;
+    isEmpty: boolean;
+}
+export interface CliScreenSnapshot {
+    text: string;
+    lineCount: number;
+    lines: CliScreenLine[];
+    nonEmptyLines: CliScreenLine[];
+    firstNonEmptyLineIndex: number;
+    lastNonEmptyLineIndex: number;
+    firstNonEmptyLine: CliScreenLine | null;
+    lastNonEmptyLine: CliScreenLine | null;
+    promptLineIndex: number;
+    promptLine: CliScreenLine | null;
+    linesAbovePrompt: CliScreenLine[];
+    linesBelowPrompt: CliScreenLine[];
+}
+export interface CliScriptInput {
+    buffer: string;
+    rawBuffer: string;
+    recentBuffer: string;
+    screenText: string;
+    screen: CliScreenSnapshot;
+    bufferScreen: CliScreenSnapshot;
+    recentScreen: CliScreenSnapshot;
+    messages: CliChatMessage[];
+    partialResponse: string;
+    promptText?: string;
+    settings?: Record<string, any>;
+    args?: Record<string, any>;
+}
+export interface CliStatusInput {
+    tail: string;
+    screenText?: string;
+    rawBuffer?: string;
+    screen: CliScreenSnapshot;
+    tailScreen: CliScreenSnapshot;
+}
+export interface CliApprovalInput {
+    buffer: string;
+    screenText?: string;
+    rawBuffer?: string;
+    tail: string;
+    screen: CliScreenSnapshot;
+    bufferScreen: CliScreenSnapshot;
+    tailScreen: CliScreenSnapshot;
+}
+export interface CliTraceEntry {
+    id: number;
+    at: number;
+    type: string;
+    status: CliSessionStatus['status'];
+    isWaitingForResponse: boolean;
+    activeModal: {
+        message: string;
+        buttons: string[];
+    } | null;
+    payload: Record<string, any>;
+}
+export interface CliProviderModule {
+    type: string;
+    name: string;
+    category: 'cli';
+    binary: string;
+    approvalKeys?: Record<number, string>;
+    sendDelayMs?: number;
+    sendKey?: string;
+    submitStrategy?: 'wait_for_echo' | 'immediate';
+    scripts?: CliScripts;
+    spawn: {
+        command: string;
+        args: string[];
+        shell: boolean;
+        env: Record<string, string>;
+    };
+    timeouts?: {
+        ptyFlush?: number;
+        dialogAccept?: number;
+        approvalCooldown?: number;
+        generatingIdle?: number;
+        idleFinish?: number;
+        maxResponse?: number;
+        shutdownGrace?: number;
+        outputSettle?: number;
+    };
+    resume?: ProviderResumeCapability;
+    _resolvedVersion?: string | null;
+    _resolvedOs?: string | null;
+    _resolvedProviderDir?: string | null;
+    _resolvedScriptDir?: string | null;
+    _resolvedScriptsPath?: string | null;
+    _resolvedScriptsSource?: string | null;
+    _versionWarning?: string | null;
+}
+export declare function sanitizeTerminalText(str: string): string;
+export declare function listCliScriptNames(scripts: CliScripts | undefined): string[];
+export declare function buildCliScreenSnapshot(text: string): CliScreenSnapshot;
+export declare const buildCliSpawnEnv: typeof sanitizeSpawnEnv;
+export declare function computeTerminalQueryTail(buffer: string): string;
+export declare function findBinary(name: string): string;
+export declare function isScriptBinary(binaryPath: string): boolean;
+export declare function looksLikeMachOOrElf(filePath: string): boolean;
+export declare function shSingleQuote(arg: string): string;
+export declare function estimatePromptDisplayLines(text: string, cols?: number): number;
+export declare function extractPromptRetrySnippet(text: string): string;
+export declare function normalizePromptText(text: string): string;
+export declare function compactPromptText(text: string): string;
+export declare function promptLikelyVisible(screenText: string, promptSnippet: string): boolean;
+export declare function normalizeScreenSnapshot(text: string): string;
+export declare function normalizeComparableMessageContent(text: string): string;
+export declare function trimPromptEchoPrefix(text: string, promptText?: string | null): string;
+export declare function getLastUserPromptText(messages: Array<{
+    role?: string;
+    content?: string;
+}> | null | undefined): string;
+export declare function looksLikeConfirmOnlyLabel(label: string): boolean;
+export declare function normalizeCliProviderForRuntime(raw: unknown): {
+    patterns: {
+        approval: RegExp[];
+    };
+};

package/src/cli-adapters/pty-transport.d.ts

@@ -0,0 +1,48 @@
+export interface PtySpawnOptions {
+    cwd: string;
+    env: Record<string, string>;
+    cols: number;
+    rows: number;
+}
+export interface PtyRuntimeWriteOwner {
+    clientId: string;
+    ownerType: 'agent' | 'user';
+}
+export interface PtyRuntimeClientInfo {
+    clientId: string;
+    type: 'daemon' | 'web' | 'local-terminal';
+    readOnly: boolean;
+}
+export interface PtyRuntimeMetadata {
+    runtimeId: string;
+    runtimeKey?: string;
+    displayName?: string;
+    workspaceLabel?: string;
+    writeOwner?: PtyRuntimeWriteOwner | null;
+    attachedClients?: PtyRuntimeClientInfo[];
+    restoredFromStorage?: boolean;
+    recoveryState?: string | null;
+    recoveryError?: string | null;
+}
+export interface PtyRuntimeTransport {
+    readonly pid: number;
+    readonly ready: Promise<void>;
+    readonly terminalQueriesHandled?: boolean;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    clearBuffer?(): void;
+    detach?(): void;
+    updateMeta?(meta: Record<string, unknown>, replace?: boolean): void;
+    getMetadata?(): PtyRuntimeMetadata | null;
+    onData(callback: (data: string) => void): void;
+    onExit(callback: (info: {
+        exitCode: number;
+    }) => void): void;
+}
+export interface PtyTransportFactory {
+    spawn(command: string, args: string[], options: PtySpawnOptions): PtyRuntimeTransport;
+}
+export declare class NodePtyTransportFactory implements PtyTransportFactory {
+    spawn(command: string, args: string[], options: PtySpawnOptions): PtyRuntimeTransport;
+}

package/src/cli-adapters/session-host-transport.d.ts

@@ -0,0 +1,20 @@
+import { type SessionHostEndpoint, type SessionHostCategory } from '@adhdev/session-host-core';
+import type { PtyRuntimeTransport, PtySpawnOptions, PtyTransportFactory } from './pty-transport.js';
+interface SessionHostPtyTransportFactoryOptions {
+    endpoint?: SessionHostEndpoint;
+    appName?: string;
+    ensureReady?: () => Promise<void>;
+    clientId: string;
+    runtimeId: string;
+    providerType: string;
+    category?: SessionHostCategory;
+    workspace: string;
+    meta?: Record<string, unknown>;
+    attachExisting?: boolean;
+}
+export declare class SessionHostPtyTransportFactory implements PtyTransportFactory {
+    private readonly options;
+    constructor(options: SessionHostPtyTransportFactoryOptions);
+    spawn(command: string, args: string[], spawnOptions: PtySpawnOptions): PtyRuntimeTransport;
+}
+export {};

package/src/cli-adapters/spawn-env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export spawn environment utilities from @adhdev/session-host-core.
+ *
+ * The canonical implementation lives in session-host-core so that both
+ * daemon-core and session-host-daemon can share it. This file exists
+ * to keep the import path short within daemon-core consumers.
+ */
+export { sanitizeSpawnEnv, applyTerminalColorEnv, ensureNodePtySpawnHelperPermissions, } from '@adhdev/session-host-core';

package/src/cli-adapters/terminal-backends/ghostty-vt-backend.d.ts

@@ -0,0 +1,16 @@
+import type { TerminalViewportBackend, TerminalViewportBackendOptions, TerminalViewportBackendPreference } from './types.js';
+export declare function resolveTerminalBackendPreference(): TerminalViewportBackendPreference;
+export declare function isGhosttyVtBackendAvailable(): boolean;
+export declare class GhosttyVtTerminalBackend implements TerminalViewportBackend {
+    readonly kind: "ghostty-vt";
+    private terminal;
+    constructor(options: TerminalViewportBackendOptions);
+    resize(rows: number, cols: number): void;
+    write(data: string): void;
+    getText(): string;
+    getCursorPosition(): {
+        col: number;
+        row: number;
+    };
+    dispose(): void;
+}

package/src/cli-adapters/terminal-backends/types.d.ts

@@ -0,0 +1,18 @@
+export type TerminalViewportBackendKind = 'xterm' | 'ghostty-vt';
+export type TerminalViewportBackendPreference = TerminalViewportBackendKind | 'auto';
+export type TerminalViewportBackendOptions = {
+    rows: number;
+    cols: number;
+    scrollback: number;
+};
+export interface TerminalViewportBackend {
+    readonly kind: TerminalViewportBackendKind;
+    resize(rows: number, cols: number): void;
+    write(data: string): void;
+    getText(): string;
+    getCursorPosition(): {
+        col: number;
+        row: number;
+    };
+    dispose(): void;
+}

package/src/cli-adapters/terminal-backends/xterm-backend.d.ts

@@ -0,0 +1,17 @@
+import type { TerminalViewportBackend, TerminalViewportBackendOptions } from './types.js';
+export declare class XtermTerminalBackend implements TerminalViewportBackend {
+    readonly kind: "xterm";
+    private rows;
+    private cols;
+    private terminal;
+    constructor(options: TerminalViewportBackendOptions);
+    resize(rows: number, cols: number): void;
+    write(data: string): void;
+    getText(): string;
+    getCursorPosition(): {
+        col: number;
+        row: number;
+    };
+    dispose(): void;
+    private createTerminal;
+}