@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/tui-state-manager.ts

@@ -0,0 +1,327 @@
+/**
+ * TuiStateManager — pure TypeScript rendering state manager.
+ *
+ * Converts InteractiveSession events into rendering state without a React dependency.
+ * The React hook subscribes to onChange and reads state for rendering.
+ */
+
+import { TuiSessionNoticeStore } from './tui-session-notice-store.js';
+
+import type { TTuiNoticeInput } from './tui-session-events.js';
+import type { IContextWindowState, IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+import type {
+  IExecutionResult,
+  IToolState,
+  TInteractiveEventName,
+} from '@robota-sdk/agent-interface-session';
+
+/** Debounce interval for streaming text notify (limits renderMarkdown frequency) */
+const STREAMING_DEBOUNCE_MS = 300;
+/** ERR-001 G3: with no provider activity for this long while thinking, hint that the
+ * connection may be stalled (well under the 120s provider idle timeout). */
+const STALL_HINT_MS = 15_000;
+/**
+ * TUI view of the core context-window state. The token fields are derived from the agent-core
+ * SSOT (`IContextWindowState`) via `Pick` so they stay structurally tied to it; `percentage` is an
+ * explicit display-facing mirror of `IContextWindowState.usedPercentage`.
+ */
+export type TContextState = Pick<IContextWindowState, 'usedTokens' | 'maxTokens'> & {
+  /** Mirror of `IContextWindowState.usedPercentage`, named for the TUI display layer. */
+  percentage: number;
+};
+
+/** Create a debounced notify — schedules at most one call per interval. */
+function createDebouncedNotify(
+  notify: () => void,
+  ms: number,
+): { schedule: () => void; flush: () => void } {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return {
+    schedule() {
+      if (!timer) {
+        timer = setTimeout(() => {
+          timer = null;
+          notify();
+        }, ms);
+      }
+    },
+    flush() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+export class TuiStateManager {
+  // ── Rendering state ───────────────────────────────────────────
+  history: IHistoryEntry[] = [];
+  /**
+   * Notices this terminal added itself (command results, init errors). They are not in the session's
+   * history, so each remembers how many session entries preceded it and is re-inserted there on sync.
+   */
+  private localNotices: { readonly entry: IHistoryEntry; readonly afterSessionEntries: number }[] =
+    [];
+  streamingText = '';
+  activeTools: IToolState[] = [];
+  isThinking = false;
+  isAborting = false;
+  pendingPrompt: string | null = null;
+  contextState: TContextState = { percentage: 0, usedTokens: 0, maxTokens: 0 };
+  executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot | null = null;
+  selectedExecutionEntryId: string | undefined;
+  /** ERR-001 G2: humanized message of the last failed turn; cleared when the next turn starts. */
+  lastErrorMessage: string | null = null;
+  /** ERR-001 G3: no stream/tool activity for STALL_HINT_MS while thinking. */
+  isStalled = false;
+  private readonly sessionNoticeStore = new TuiSessionNoticeStore();
+  /** Bounded render-only projection; never merged into canonical session history. */
+  readonly sessionEventNotices = this.sessionNoticeStore.notices;
+
+  /** Called after any state change. React hook sets this to trigger re-render. */
+  onChange: (() => void) | null = null;
+
+  // ── Internal ──────────────────────────────────────────────────
+  private streamBuf = '';
+  private debouncedStreamNotify = createDebouncedNotify(() => this.notify(), STREAMING_DEBOUNCE_MS);
+  private stallTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /** (Re)start the dead-air timer — any provider activity proves the connection is alive. */
+  private armStallTimer(): void {
+    this.clearStallTimer();
+    this.stallTimer = setTimeout(() => {
+      this.stallTimer = null;
+      this.isStalled = true;
+      this.notify();
+    }, STALL_HINT_MS);
+  }
+
+  private clearStallTimer(): void {
+    if (this.stallTimer) {
+      clearTimeout(this.stallTimer);
+      this.stallTimer = null;
+    }
+    if (this.isStalled) {
+      this.isStalled = false;
+    }
+  }
+
+  private notify(): void {
+    this.onChange?.();
+  }
+
+  // ── Event handlers (InteractiveSession → state) ───────────────
+
+  onTextDelta = (delta: string): void => {
+    if (this.isThinking) this.armStallTimer();
+    this.streamBuf += delta;
+    this.streamingText = this.streamBuf;
+    this.debouncedStreamNotify.schedule();
+  };
+
+  onToolStart = (state: IToolState): void => {
+    // RUNTIME-39: a running tool is legitimate activity, not a stalled provider connection —
+    // suppress the dead-air hint for the duration of the tool run (re-armed in onToolEnd).
+    this.clearStallTimer();
+    this.activeTools = [...this.activeTools, state];
+    this.notify();
+  };
+
+  onToolEnd = (state: IToolState): void => {
+    // findLastIndex: when same tool runs concurrently, match the most recently started instance
+    const idx = this.activeTools.findLastIndex((t) => t.toolName === state.toolName && t.isRunning);
+    if (idx !== -1) {
+      const updated = [...this.activeTools];
+      updated[idx] = state;
+      this.activeTools = updated;
+    }
+    // RUNTIME-39: re-arm the dead-air watch only once no tool is still running and the turn is
+    // still in progress — otherwise the provider is again the thing we're waiting on.
+    if (this.isThinking && !this.activeTools.some((t) => t.isRunning)) {
+      this.armStallTimer();
+    }
+    this.notify();
+  };
+
+  onThinking = (thinking: boolean): void => {
+    this.isThinking = thinking;
+    if (thinking) {
+      // Clear at START of new execution (preserves previous result until next)
+      this.debouncedStreamNotify.flush();
+      this.streamBuf = '';
+      this.streamingText = '';
+      this.activeTools = [];
+      this.lastErrorMessage = null;
+      this.armStallTimer();
+    } else {
+      this.isAborting = false;
+      this.activeTools = [];
+      this.clearStallTimer();
+    }
+    this.notify();
+  };
+
+  onComplete = (result: IExecutionResult): void => {
+    this.clearStallTimer();
+    this.debouncedStreamNotify.flush();
+    this.streamBuf = '';
+    this.streamingText = '';
+    this.activeTools = [];
+    this.contextState = {
+      percentage: result.contextState.usedPercentage,
+      usedTokens: result.contextState.usedTokens,
+      maxTokens: result.contextState.maxTokens,
+    };
+    this.notify();
+  };
+
+  onInterrupted = (): void => {
+    this.clearStallTimer();
+    this.debouncedStreamNotify.flush();
+    this.streamBuf = '';
+    this.streamingText = '';
+    this.activeTools = [];
+    this.notify();
+  };
+
+  onError = (error?: Error): void => {
+    // The partial answer is preserved as an interrupted history entry by the framework
+    // (ERR-001); clearing the local stream buffer here no longer loses it.
+    this.clearStallTimer();
+    this.lastErrorMessage = error?.message ?? 'Unknown error';
+    this.debouncedStreamNotify.flush();
+    this.streamBuf = '';
+    this.streamingText = '';
+    this.activeTools = [];
+    this.notify();
+  };
+
+  onContextUpdate = (state: IContextWindowState): void => {
+    this.setContextState({
+      percentage: state.usedPercentage,
+      usedTokens: state.usedTokens,
+      maxTokens: state.maxTokens,
+    });
+  };
+
+  // ── State updates from external sources ───────────────────────
+
+  /**
+   * Sync history from InteractiveSession — authoritative SSOT replace (SCREEN-010: no front-windowing).
+   * The session history grows monotonically during a session, so Ink `<Static>` (count-based) renders
+   * only the newly-appended tail; committed lines already in terminal scrollback are never re-printed.
+   */
+  syncHistory(entries: IHistoryEntry[]): void {
+    if (entries.length === 0) return;
+    // `<Static>` counts what it already printed, so a local notice dropped here would shift every
+    // later index by one and the next committed entry (the assistant's answer) would never print.
+    const merged: IHistoryEntry[] = [];
+    let next = 0;
+    for (const notice of this.localNotices) {
+      const upTo = Math.min(notice.afterSessionEntries, entries.length);
+      while (next < upTo) merged.push(entries[next++]!);
+      merged.push(notice.entry);
+    }
+    while (next < entries.length) merged.push(entries[next++]!);
+    this.history = merged;
+    this.notify();
+  }
+
+  /** Add a notice this terminal owns; it survives the next session-history sync in place. */
+  addEntry(entry: IHistoryEntry): void {
+    this.localNotices.push({
+      entry,
+      afterSessionEntries: this.history.length - this.localNotices.length,
+    });
+    this.history = [...this.history, entry];
+    this.notify();
+  }
+
+  /** Echo the user's prompt at once; the session's own user entry replaces it on the next sync. */
+  addUserEcho(entry: IHistoryEntry): void {
+    this.history = [...this.history, entry];
+    this.notify();
+  }
+
+  clearHistory(): void {
+    this.history = [];
+    this.localNotices = [];
+    this.debouncedStreamNotify.flush();
+    this.streamBuf = '';
+    this.streamingText = '';
+    this.activeTools = [];
+    this.notify();
+  }
+
+  /** Update pending prompt state */
+  setPendingPrompt(prompt: string | null): void {
+    this.pendingPrompt = prompt;
+    this.notify();
+  }
+
+  /** Set aborting flag */
+  setAborting(aborting: boolean): void {
+    this.isAborting = aborting;
+    this.notify();
+  }
+
+  /** Update context state */
+  setContextState(state: TContextState): void {
+    this.contextState = state;
+    this.notify();
+  }
+
+  addSessionEventNotice(input: TTuiNoticeInput): void {
+    this.sessionNoticeStore.add(input);
+    this.notify();
+  }
+
+  addAttentionRecap(line: string): void {
+    this.sessionNoticeStore.addAttentionRecap(line);
+    this.notify();
+  }
+
+  addSessionEventDeliveryError(error: Error, event: TInteractiveEventName): void {
+    this.sessionNoticeStore.addDeliveryError(error, event);
+    this.notify();
+  }
+
+  syncExecutionWorkspaceSnapshot(snapshot: IExecutionWorkspaceSnapshot): void {
+    const currentSelection = this.selectedExecutionEntryId;
+    const hasCurrentSelection =
+      currentSelection !== undefined &&
+      snapshot.entries.some((entry) => entry.id === currentSelection);
+    const selectedExecutionEntryId = hasCurrentSelection
+      ? currentSelection
+      : (snapshot.selectedEntryId ?? snapshot.entries[0]?.id);
+    this.executionWorkspaceSnapshot = {
+      ...snapshot,
+      ...(selectedExecutionEntryId ? { selectedEntryId: selectedExecutionEntryId } : {}),
+    };
+    this.selectedExecutionEntryId = selectedExecutionEntryId;
+    this.notify();
+  }
+
+  selectExecutionWorkspaceEntry(entryId: string): void {
+    if (!this.executionWorkspaceSnapshot?.entries.some((entry) => entry.id === entryId)) return;
+    this.selectedExecutionEntryId = entryId;
+    this.executionWorkspaceSnapshot = {
+      ...this.executionWorkspaceSnapshot,
+      selectedEntryId: entryId,
+    };
+    this.notify();
+  }
+
+  /**
+   * RUNTIME-52: release every timer this manager owns and detach the render callback. Called by the
+   * channel's teardown (`stop()`); after dispose the manager must never fire `onChange` or trip the
+   * stall hint on a discarded session.
+   */
+  dispose(): void {
+    this.clearStallTimer();
+    this.debouncedStreamNotify.flush();
+    this.onChange = null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+/** UI-layer permission types for the Ink TUI */
+
+import type { TToolArgs } from '@robota-sdk/agent-core';
+import type { TPermissionResultValue } from '@robota-sdk/agent-interface-session';
+
+/**
+ * Permission result: true (allow once), false (deny), 'allow-session' (remember for session),
+ * or 'allow-project' (persist through the host-selected project settings writer).
+ */
+export type TPermissionResult = TPermissionResultValue; // issue #2052: owned by agent-interface-session
+
+export interface IPendingPermissionRequest {
+  toolName: string;
+  toolArgs: TToolArgs;
+  canPersistProjectPermission?: boolean;
+  /** The peer session whose message this call serves, when a peer turn asked. */
+  requestedByPeer?: string;
+  resolve: (result: TPermissionResult) => void;
+}

package/src/use-terminal-title.ts

@@ -0,0 +1,29 @@
+import { useEffect } from 'react';
+
+import { useProductDisplayName } from './product-display-name-context.js';
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+
+/**
+ * Set the terminal's window title from the session name.
+ *
+ * Split out of `App.tsx` under SEC-019 (issue #2022) by responsibility: this is the one place the TUI
+ * writes an escape sequence to stdout directly rather than through Ink, which makes it the one place
+ * where a value is interpolated INTO terminal syntax rather than rendered as content. Keeping it
+ * inside a 600-line component is what let it sit unexamined next to code that never touches an
+ * escape.
+ *
+ * `sessionName` is untrusted — a session can be named from a prompt, and a name containing BEL or ESC
+ * terminates the OSC early, so everything after it is read by the terminal as its own command.
+ *
+ * Both the host-selected product name and the session name are sanitized separately from the
+ * `\x1b]0;` … `\x07` framing this module deliberately writes.
+ */
+export function useTerminalTitle(sessionName: string | undefined): void {
+  const productDisplayName = useProductDisplayName();
+  useEffect(() => {
+    const safeName = sanitizeTerminalText(sessionName ?? '');
+    const safeProductName = sanitizeTerminalText(productDisplayName);
+    const title = safeName ? `${safeProductName} — ${safeName}` : safeProductName;
+    process.stdout.write(`\x1b]0;${title}\x07`);
+  }, [sessionName, productDisplayName]);
+}