@love-moon/tui-driver 0.2.0

package/src/driver/StateMachine.ts

@@ -0,0 +1,90 @@
+import { EventEmitter } from "events";
+
+export type TuiState =
+  | "IDLE"
+  | "BOOT"
+  | "WAIT_READY"
+  | "PREPARE_TURN"
+  | "TYPE_PROMPT"
+  | "SUBMIT"
+  | "WAIT_STREAM_START"
+  | "WAIT_STREAM_END"
+  | "CAPTURE"
+  | "DONE"
+  | "ERROR"
+  | "RECOVERY";
+
+export interface StateTransition {
+  from: TuiState;
+  to: TuiState;
+  timestamp: number;
+}
+
+export interface StateMachineEvents {
+  stateChange: (transition: StateTransition) => void;
+  error: (error: Error, state: TuiState) => void;
+}
+
+export class StateMachine extends EventEmitter {
+  private _state: TuiState = "IDLE";
+  private _history: StateTransition[] = [];
+  private _stateStartTime: number = Date.now();
+
+  get state(): TuiState {
+    return this._state;
+  }
+
+  get history(): readonly StateTransition[] {
+    return this._history;
+  }
+
+  get stateElapsedMs(): number {
+    return Date.now() - this._stateStartTime;
+  }
+
+  transition(to: TuiState): void {
+    const from = this._state;
+    const timestamp = Date.now();
+
+    const transition: StateTransition = { from, to, timestamp };
+    this._history.push(transition);
+    this._state = to;
+    this._stateStartTime = timestamp;
+
+    this.emit("stateChange", transition);
+  }
+
+  transitionTo(...states: TuiState[]): void {
+    for (const state of states) {
+      this.transition(state);
+    }
+  }
+
+  isIn(...states: TuiState[]): boolean {
+    return states.includes(this._state);
+  }
+
+  reset(): void {
+    this._state = "IDLE";
+    this._history = [];
+    this._stateStartTime = Date.now();
+  }
+
+  error(err: Error): void {
+    const previousState = this._state;
+    this.transition("ERROR");
+    this.emit("error", err, previousState);
+  }
+
+  recover(): void {
+    this.transition("RECOVERY");
+  }
+
+  getLastTransition(): StateTransition | undefined {
+    return this._history[this._history.length - 1];
+  }
+
+  getTransitionsSince(timestamp: number): StateTransition[] {
+    return this._history.filter(t => t.timestamp >= timestamp);
+  }
+}

package/src/driver/TuiDriver.ts

@@ -0,0 +1,624 @@
+import { EventEmitter } from "events";
+import { PtySession } from "../pty/PtySession.js";
+import { HeadlessScreen } from "../term/HeadlessScreen.js";
+import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
+import { ExpectEngine } from "../expect/ExpectEngine.js";
+import { Matchers } from "../expect/Matchers.js";
+import { OutputExtractor } from "../extract/OutputExtractor.js";
+import { computeLineDiff } from "../extract/Diff.js";
+import { TuiProfile, TuiSignals } from "./TuiProfile.js";
+import { StateMachine, TuiState } from "./StateMachine.js";
+
+export interface TuiDriverOptions {
+  profile: TuiProfile;
+  debug?: boolean;
+  onSnapshot?: (snapshot: ScreenSnapshot, state: TuiState) => void;
+  onSignals?: (signals: TuiScreenSignals, snapshot: ScreenSnapshot, state: TuiState) => void;
+}
+
+export interface AskResult {
+  success: boolean;
+  answer: string;
+  beforeSnapshot: ScreenSnapshot;
+  afterSnapshot: ScreenSnapshot;
+  elapsedMs: number;
+  error?: Error;
+  signals?: TuiScreenSignals;
+  promptLine?: string;
+  replyText?: string;
+  replyBlocks?: string[];
+  replyInProgress?: boolean;
+  statusLine?: string;
+  statusDoneLine?: string;
+}
+
+export interface TuiScreenSignals {
+  hasPrompt: boolean;
+  promptLine?: string;
+  replyText?: string;
+  replyBlocks?: string[];
+  replyInProgress: boolean;
+  statusLine?: string;
+  statusDoneLine?: string;
+}
+
+export class TuiDriver extends EventEmitter {
+  private pty: PtySession;
+  private screen: HeadlessScreen;
+  private expect: ExpectEngine;
+  private stateMachine: StateMachine;
+  private profile: TuiProfile;
+  private debug: boolean;
+  private onSnapshot?: (snapshot: ScreenSnapshot, state: TuiState) => void;
+  private onSignals?: (signals: TuiScreenSignals, snapshot: ScreenSnapshot, state: TuiState) => void;
+  private isBooted = false;
+
+  constructor(options: TuiDriverOptions) {
+    super();
+    this.profile = options.profile;
+    this.debug = options.debug ?? false;
+    this.onSnapshot = options.onSnapshot;
+    this.onSignals = options.onSignals;
+
+    const cols = this.profile.cols ?? 120;
+    const rows = this.profile.rows ?? 40;
+    const scrollback = this.profile.scrollback ?? 5000;
+
+    this.pty = new PtySession(
+      this.profile.command,
+      this.profile.args,
+      { cols, rows, env: this.profile.env }
+    );
+
+    this.screen = new HeadlessScreen({
+      cols,
+      rows,
+      scrollback,
+      onTerminalReply: (data) => this.pty.writeResponse(data),
+    });
+    this.expect = new ExpectEngine(this.screen);
+    this.stateMachine = new StateMachine();
+
+    this.setupEventHandlers();
+  }
+
+  private setupEventHandlers(): void {
+    this.pty.onData((chunk) => {
+      this.screen.write(chunk);
+      if (this.debug) {
+        this.log(`PTY data: ${chunk.length} bytes`);
+      }
+    });
+
+    this.pty.onExit((code, signal) => {
+      this.log(`PTY exited: code=${code}, signal=${signal}`);
+      this.isBooted = false;
+      this.emit("exit", code, signal);
+    });
+
+    this.stateMachine.on("stateChange", (transition) => {
+      this.log(`State: ${transition.from} -> ${transition.to}`);
+      this.emit("stateChange", transition);
+    });
+
+    this.stateMachine.on("error", (err, state) => {
+      this.log(`Error in state ${state}: ${err.message}`);
+      this.emit("error", err, state);
+    });
+  }
+
+  private log(message: string): void {
+    if (this.debug) {
+      console.log(`[TuiDriver] ${message}`);
+    }
+  }
+
+  get state(): TuiState {
+    return this.stateMachine.state;
+  }
+
+  get running(): boolean {
+    return this.pty.isRunning;
+  }
+
+  async boot(): Promise<void> {
+    if (this.isBooted) {
+      return;
+    }
+
+    this.stateMachine.transition("BOOT");
+    this.pty.spawn();
+
+    const bootTimeout = this.resolveTimeout(this.profile.timeouts?.boot, 15000);
+    const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
+    const trustMatcher = this.profile.anchors.trust
+      ? Matchers.anyOf(this.profile.anchors.trust)
+      : null;
+    const startTime = Date.now();
+    let readySince: number | null = null;
+    let lastTrustConfirmAt = 0;
+
+    while (true) {
+      if (!this.running) {
+        throw new Error("Boot failed: TUI process exited before ready");
+      }
+
+      const now = Date.now();
+      const snapshot = this.screen.snapshot();
+
+      if (readyMatcher(snapshot)) {
+        if (readySince === null) {
+          readySince = now;
+        } else if (now - readySince >= 300) {
+          break;
+        }
+      } else {
+        readySince = null;
+      }
+
+      if (trustMatcher && trustMatcher(snapshot) && now - lastTrustConfirmAt >= 1500) {
+        lastTrustConfirmAt = now;
+        this.log("Trust prompt detected, confirming...");
+        await this.pty.sendKeys(this.profile.keys.trustConfirm ?? ["ENTER"], 0);
+      }
+
+      if (Number.isFinite(bootTimeout) && now - startTime >= bootTimeout) {
+        throw new Error("Boot timeout: TUI did not become ready");
+      }
+
+      await this.sleep(100);
+    }
+
+    this.isBooted = true;
+    this.stateMachine.transition("WAIT_READY");
+    this.captureSnapshot("boot_complete");
+  }
+
+  async ensureReady(): Promise<void> {
+    if (!this.isBooted) {
+      await this.boot();
+      return;
+    }
+
+    const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
+    const readyTimeout = this.resolveTimeout(this.profile.timeouts?.ready, 10000);
+
+    const result = await this.expect.until({
+      name: "ENSURE_READY",
+      match: readyMatcher,
+      stableMs: 200,
+      timeoutMs: readyTimeout,
+    });
+
+    if (!result.success) {
+      await this.recovery();
+      throw new Error("TUI not ready after recovery");
+    }
+  }
+
+  async ask(prompt: string): Promise<AskResult> {
+    const startTime = Date.now();
+
+    try {
+      await this.ensureReady();
+
+      this.stateMachine.transition("PREPARE_TURN");
+      await this.prepareTurn();
+
+      this.stateMachine.transition("TYPE_PROMPT");
+      await this.typePrompt(prompt);
+      await this.sleep(100);
+
+      const preSubmitSnapshot = this.captureSnapshot("before_submit");
+
+      this.stateMachine.transition("SUBMIT");
+      await this.submit();
+
+      // 在 submit 之后保存快照，这样 diff 只包含 AI 的回答，不包含 prompt
+      const beforeSnapshot = this.captureSnapshot("after_submit");
+
+      this.stateMachine.transition("WAIT_STREAM_START");
+      await this.waitStreamStart(preSubmitSnapshot);
+
+      this.stateMachine.transition("WAIT_STREAM_END");
+      await this.waitStreamEnd();
+
+      this.stateMachine.transition("CAPTURE");
+      const afterSnapshot = this.captureSnapshot("after_response");
+
+      const answer = this.extractAnswer(beforeSnapshot, afterSnapshot);
+      const signals = this.getSignals(afterSnapshot);
+
+      this.stateMachine.transition("DONE");
+
+      return {
+        success: true,
+        answer,
+        beforeSnapshot,
+        afterSnapshot,
+        elapsedMs: Date.now() - startTime,
+        signals,
+        promptLine: signals.promptLine,
+        replyText: signals.replyText,
+        replyBlocks: signals.replyBlocks,
+        replyInProgress: signals.replyInProgress,
+        statusLine: signals.statusLine,
+        statusDoneLine: signals.statusDoneLine,
+      };
+    } catch (error) {
+      this.stateMachine.error(error as Error);
+      const signals = this.getSignals(this.screen.snapshot());
+      return {
+        success: false,
+        answer: "",
+        beforeSnapshot: this.screen.snapshot(),
+        afterSnapshot: this.screen.snapshot(),
+        elapsedMs: Date.now() - startTime,
+        error: error as Error,
+        signals,
+        promptLine: signals.promptLine,
+        replyText: signals.replyText,
+        replyBlocks: signals.replyBlocks,
+        replyInProgress: signals.replyInProgress,
+        statusLine: signals.statusLine,
+        statusDoneLine: signals.statusDoneLine,
+      };
+    }
+  }
+
+  private async prepareTurn(): Promise<void> {
+    if (this.profile.preflightKeys && this.profile.preflightKeys.length > 0) {
+      await this.pty.sendKeys(this.profile.preflightKeys, 50);
+      await this.sleep(100);
+    }
+  }
+
+  private async typePrompt(prompt: string): Promise<void> {
+    await this.pty.writeChunked(prompt, 300, 20);
+  }
+
+  private async submit(): Promise<void> {
+    await this.pty.sendKeys(this.profile.keys.submit, 50);
+  }
+
+  private async waitStreamStart(previousSnapshot: ScreenSnapshot): Promise<void> {
+    const timeout = this.resolveTimeout(this.profile.timeouts?.streamStart, 10000);
+
+    if (this.profile.anchors.busy && this.profile.anchors.busy.length > 0) {
+      const busyPatterns = this.profile.anchors.busy;
+      const previousScrollback = previousSnapshot.scrollbackText;
+      const startMatcher = (snapshot: ScreenSnapshot): boolean => {
+        const { added } = computeLineDiff(previousScrollback, snapshot.scrollbackText);
+        return added.some(line => busyPatterns.some(pattern => pattern.test(line)));
+      };
+      const result = await this.expect.until({
+        name: "STREAM_START",
+        match: startMatcher,
+        stableMs: 100,
+        timeoutMs: timeout,
+      });
+      if (!result.success) {
+        throw new Error("Stream start timeout: no response detected");
+      }
+    } else {
+      const result = await this.expect.waitForChange(timeout);
+      if (!result.success) {
+        throw new Error("Stream start timeout: no screen change detected");
+      }
+    }
+  }
+
+  private async waitStreamEnd(): Promise<void> {
+    const idleMs = this.profile.timeouts?.idle ?? 800;
+    const timeout = this.resolveTimeout(this.profile.timeouts?.streamEnd, 120000);
+
+    const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
+    const busyMatcher = this.profile.anchors.busy?.length
+      ? Matchers.anyOf(this.profile.anchors.busy)
+      : null;
+    const replyStartMatcher = this.profile.signals?.replyStart?.length
+      ? Matchers.anyOf(this.profile.signals.replyStart, "scrollback")
+      : null;
+    const promptHintMatcher = this.profile.signals?.promptHint?.length
+      ? Matchers.anyOf(this.profile.signals.promptHint)
+      : null;
+    const statusMatcher = this.profile.signals?.status?.length
+      ? Matchers.anyOf(this.profile.signals.status)
+      : null;
+    const statusDoneMatcher = this.profile.signals?.statusDone?.length
+      ? Matchers.anyOf(this.profile.signals.statusDone)
+      : null;
+
+    // 组合条件：屏幕 idle + ready anchor 出现 + busy anchor 消失
+    const completeMatcher = busyMatcher
+      ? Matchers.and(readyMatcher, Matchers.not(busyMatcher))
+      : readyMatcher;
+
+    if (this.profile.requireReplyStart && replyStartMatcher) {
+      const replyOrHintResult = await this.expect.until({
+        name: "STREAM_END_REPLY_OR_HINT",
+        match: promptHintMatcher
+          ? Matchers.or(replyStartMatcher, promptHintMatcher)
+          : replyStartMatcher,
+        stableMs: 200,
+        timeoutMs: timeout,
+      });
+      if (!replyOrHintResult.success) {
+        throw new Error("Stream end timeout: no reply detected");
+      }
+
+      await this.waitForScrollbackIdle(idleMs, timeout);
+
+      if (statusMatcher) {
+        const statusClearResult = await this.expect.until({
+          name: "STREAM_END_STATUS_CLEAR",
+          match: statusDoneMatcher
+            ? Matchers.or(Matchers.not(statusMatcher), statusDoneMatcher)
+            : Matchers.not(statusMatcher),
+          stableMs: 300,
+          timeoutMs: timeout,
+        });
+        if (!statusClearResult.success) {
+          throw new Error("Stream end timeout: status did not clear");
+        }
+      }
+    } else {
+      // 先等待屏幕稳定
+      const idleResult = await this.expect.untilIdle({
+        name: "STREAM_END_IDLE",
+        idleMs,
+        timeoutMs: timeout,
+      });
+      if (!idleResult.success) {
+        throw new Error("Stream end timeout: screen did not become idle");
+      }
+    }
+
+    // 再确认 ready 状态
+    if (this.profile.requireReplyStart) {
+      const readyResult = await this.expect.until({
+        name: "STREAM_END_READY",
+        match: completeMatcher,
+        stableMs: 500,
+        timeoutMs: 3000,
+      });
+      if (!readyResult.success) {
+        this.log("Ready prompt not detected after reply completion");
+      }
+    } else {
+      const readyResult = await this.expect.until({
+        name: "STREAM_END_READY",
+        match: completeMatcher,
+        stableMs: 500,
+        timeoutMs: 10000,
+      });
+      if (!readyResult.success) {
+        throw new Error("Stream end timeout: ready prompt not detected");
+      }
+    }
+  }
+
+  private extractAnswer(before: ScreenSnapshot, after: ScreenSnapshot): string {
+    const extractor = new OutputExtractor(this.profile.extraction);
+    const primary = extractor.extract(before, after).text;
+    this.log(`extractAnswer: primary="${primary?.slice(0, 200) || '(empty)'}"`);
+    if (primary) {
+      return primary;
+    }
+
+    const signals = this.getSignals(after);
+    this.log(`extractAnswer: signals.replyText="${signals.replyText?.slice(0, 200) || '(empty)'}" blocks=${signals.replyBlocks?.length || 0}`);
+    const hasReplySignal = Boolean(
+      (signals.replyText && signals.replyText.trim()) ||
+      (Array.isArray(signals.replyBlocks) && signals.replyBlocks.length > 0)
+    );
+    if (!hasReplySignal) {
+      return "";
+    }
+
+    // Fallback: if includeLinePatterns misses the assistant block, retry with relaxed extraction.
+    const relaxedExtractor = new OutputExtractor({
+      ...this.profile.extraction,
+      includeLinePatterns: undefined,
+    });
+    const relaxed = relaxedExtractor.extract(before, after).text;
+    this.log(`extractAnswer: relaxed="${relaxed?.slice(0, 200) || '(empty)'}"`);
+    return relaxed;
+  }
+
+  private async recovery(): Promise<void> {
+    this.stateMachine.recover();
+
+    if (this.profile.keys.cancel) {
+      await this.pty.sendKeys(this.profile.keys.cancel, 100);
+      await this.sleep(500);
+    }
+
+    await this.pty.sendKeys(["ESC", "ESC"], 50);
+    await this.sleep(300);
+
+    const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
+    const result = await this.expect.until({
+      name: "RECOVERY_READY",
+      match: readyMatcher,
+      stableMs: 300,
+      timeoutMs: 5000,
+    });
+
+    if (!result.success) {
+      await this.restart();
+    }
+  }
+
+  private async restart(): Promise<void> {
+    this.log("Restarting PTY...");
+    this.pty.kill();
+    this.screen.reset();
+    this.isBooted = false;
+    await this.sleep(500);
+    await this.boot();
+  }
+
+  private captureSnapshot(label: string): ScreenSnapshot {
+    const snapshot = this.screen.snapshot();
+    if (this.onSnapshot) {
+      this.onSnapshot(snapshot, this.stateMachine.state);
+    }
+    const signals = this.getSignals(snapshot);
+    if (this.onSignals) {
+      this.onSignals(signals, snapshot, this.stateMachine.state);
+    }
+    this.emit("signals", signals, snapshot, this.stateMachine.state);
+    this.log(`Snapshot [${label}]: hash=${snapshot.hash}`);
+    return snapshot;
+  }
+
+  snapshot(): ScreenSnapshot {
+    return this.screen.snapshot();
+  }
+
+  getSignals(snapshot: ScreenSnapshot = this.screen.snapshot()): TuiScreenSignals {
+    const signals = this.profile.signals;
+    if (!signals) {
+      return {
+        hasPrompt: false,
+        replyInProgress: false,
+      };
+    }
+
+    const lines = snapshot.scrollbackText.split("\n");
+    // Log lines that match replyStart pattern
+    const replyStartLines = lines.filter(line =>
+      signals.replyStart?.some(pattern => pattern.test(line))
+    );
+    this.log(`getSignals: scrollback lines=${lines.length}, replyStart matches: ${JSON.stringify(replyStartLines.slice(0, 3))}`);
+    const promptLine = this.findLastMatch(lines, signals.prompt);
+    const statusLine = this.findLastMatch(lines, signals.status);
+    const statusDoneLine = this.findLastMatch(lines, signals.statusDone);
+    const reply = this.extractReplyBlocks(lines, signals);
+    this.log(`getSignals: promptLine="${promptLine || '(none)'}" statusLine="${statusLine || '(none)'}" reply.text="${reply.text?.slice(0, 100) || '(none)'}" reply.blocks=${reply.blocks.length}`);
+
+    return {
+      hasPrompt: Boolean(promptLine),
+      promptLine: promptLine ?? undefined,
+      replyText: reply.text ?? undefined,
+      replyBlocks: reply.blocks.length > 0 ? reply.blocks : undefined,
+      replyInProgress: reply.inProgress,
+      statusLine: statusLine ?? undefined,
+      statusDoneLine: statusDoneLine ?? undefined,
+    };
+  }
+
+  async sendKeys(keys: string[]): Promise<void> {
+    await this.pty.sendKeys(keys, 50);
+  }
+
+  async write(data: string): Promise<void> {
+    this.pty.write(data);
+  }
+
+  kill(): void {
+    this.pty.kill();
+    this.screen.dispose();
+    this.isBooted = false;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private resolveTimeout(timeoutMs: number | undefined, defaultTimeoutMs: number): number {
+    const value = timeoutMs ?? defaultTimeoutMs;
+    if (!Number.isFinite(value) || value <= 0) {
+      return Number.POSITIVE_INFINITY;
+    }
+    return value;
+  }
+
+  private async waitForScrollbackIdle(idleMs: number, timeoutMs: number): Promise<void> {
+    const startTime = Date.now();
+    let lastHash = ScreenSnapshot.computeHash(this.screen.snapshot().scrollbackText);
+    let lastChangeTime = Date.now();
+
+    while (true) {
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= timeoutMs) {
+        throw new Error("Stream end timeout: scrollback did not become idle");
+      }
+
+      const currentHash = ScreenSnapshot.computeHash(this.screen.snapshot().scrollbackText);
+      if (currentHash !== lastHash) {
+        lastHash = currentHash;
+        lastChangeTime = Date.now();
+      } else if (Date.now() - lastChangeTime >= idleMs) {
+        return;
+      }
+
+      await this.sleep(100);
+    }
+  }
+
+  private findLastMatch(lines: string[], patterns?: RegExp[]): string | null {
+    if (!patterns || patterns.length === 0) {
+      return null;
+    }
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+      if (patterns.some((pattern) => pattern.test(line))) {
+        return line;
+      }
+    }
+
+    return null;
+  }
+
+  private extractReplyBlocks(
+    lines: string[],
+    signals: TuiSignals
+  ): { text: string | null; inProgress: boolean; blocks: string[] } {
+    const startPatterns = signals.replyStart ?? [];
+    if (startPatterns.length === 0) {
+      return { text: null, inProgress: false, blocks: [] };
+    }
+
+    const stopPatterns = signals.replyStop ?? [];
+    let collecting = false;
+    let current: string[] = [];
+    const blocks: string[] = [];
+
+    for (const line of lines) {
+      if (startPatterns.some((pattern) => pattern.test(line))) {
+        if (collecting && current.length > 0) {
+          blocks.push(current.join("\n"));
+          this.log(`extractReplyBlocks: saved block with ${current.length} lines`);
+        }
+        collecting = true;
+        current = [line];
+        continue;
+      }
+
+      if (collecting) {
+        if (stopPatterns.some((pattern) => pattern.test(line))) {
+          blocks.push(current.join("\n"));
+          this.log(`extractReplyBlocks: stopped at "${line.slice(0, 50)}", saved block with ${current.length} lines`);
+          collecting = false;
+          current = [];
+          continue;
+        }
+        current.push(line);
+      }
+    }
+
+    if (collecting && current.length > 0) {
+      this.log(`extractReplyBlocks: still collecting, current has ${current.length} lines`);
+      return { text: current.join("\n"), inProgress: true, blocks };
+    }
+
+    if (blocks.length > 0) {
+      return { text: blocks[blocks.length - 1], inProgress: false, blocks };
+    }
+
+    return { text: null, inProgress: false, blocks };
+  }
+}