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

package/src/__tests__/ui-intent-rendering.test.tsx

@@ -0,0 +1,291 @@
+/**
+ * CMD-004 Phase 2 Stage C (TC-04): the TUI is a pure renderer — the four UI screens open from the
+ * requester-routed `ui_intent` session event (never from legacy `result.effects` branches), the
+ * session title updates from the broadcast `session_renamed` event (never by the TUI mutating the
+ * session), and the statusline re-reads its persisted settings when a command result arrives
+ * (refresh-on-result — the HOST applies the patch; the TUI no longer writes settings).
+ *
+ * Red-first evidence: written against the pre-Stage-C hook (which still consumed legacy effects and
+ * had no session subscription) — every behavioral case below failed there.
+ */
+
+import { Text } from 'ink';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useSideEffects } from '../hooks/useSideEffects.js';
+import { useStatusLineSettings } from '../hooks/useStatusLineSettings.js';
+import { TuiCliAdapterProvider } from '../tui-cli-adapter-context.js';
+import { TUI_SESSION_EVENT_CLASSIFICATION } from '../tui-session-events.js';
+
+import type { IUseSideEffectsOptions, IUseSideEffectsResult } from '../hooks/side-effects-types.js';
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+const FRAME_DEADLINE_MS = 3000;
+
+async function waitUntil(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + FRAME_DEADLINE_MS;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  expect(predicate()).toBe(true);
+}
+
+type TSessionListener = (payload: unknown) => void;
+
+/** Minimal InteractiveSession stand-in: a typed event emitter (`on`/`off`/`emit`). */
+class FakeSessionEmitter {
+  private readonly listeners = new Map<string, Set<TSessionListener>>();
+
+  on(event: string, handler: TSessionListener): void {
+    const set = this.listeners.get(event) ?? new Set<TSessionListener>();
+    set.add(handler);
+    this.listeners.set(event, set);
+  }
+
+  off(event: string, handler: TSessionListener): void {
+    this.listeners.get(event)?.delete(handler);
+  }
+
+  emit(event: string, payload: unknown): void {
+    for (const handler of [...(this.listeners.get(event) ?? [])]) handler(payload);
+  }
+
+  listenerCount(event: string): number {
+    return this.listeners.get(event)?.size ?? 0;
+  }
+
+  subscribedEvents(): string[] {
+    return [...this.listeners].filter(([, handlers]) => handlers.size > 0).map(([event]) => event);
+  }
+
+  setName = vi.fn();
+  getName = (): string | undefined => undefined;
+}
+
+function fakeCliAdapter(store: () => Record<string, TUniversalValue>): ITuiCliAdapter {
+  return {
+    getUserSettingsPath: () => '/tmp/fake-settings.json',
+    readSettings: () => store(),
+    reloadPluginCommandSource: vi.fn(),
+    applyActiveModelChange: vi.fn().mockReturnValue({ applied: true }),
+    getGitBranch: vi.fn().mockReturnValue(undefined),
+    getProviderDisplayName: vi.fn((type: string) => type),
+  } as unknown as ITuiCliAdapter;
+}
+
+interface IHarness {
+  session: FakeSessionEmitter;
+  result: () => IUseSideEffectsResult;
+  lastFrame: () => string | undefined;
+  unmount: () => void;
+  spies: {
+    setSessionName: ReturnType<typeof vi.fn>;
+    refreshStatusLineSettings: ReturnType<typeof vi.fn>;
+    refreshAppearanceSettings: ReturnType<typeof vi.fn>;
+    openAgentSwitcher: ReturnType<typeof vi.fn>;
+    baseHandleSubmit: ReturnType<typeof vi.fn>;
+  };
+}
+
+function mountHarness(): IHarness {
+  const session = new FakeSessionEmitter();
+  const spies = {
+    setSessionName: vi.fn(),
+    refreshStatusLineSettings: vi.fn(),
+    refreshAppearanceSettings: vi.fn(),
+    openAgentSwitcher: vi.fn(),
+    baseHandleSubmit: vi.fn(async () => {}),
+  };
+  const resultRef: { current: IUseSideEffectsResult | null } = { current: null };
+
+  // Superset options object: carries both the pre-Stage-C fields (queue, addEntry, …) and the
+  // Stage-C fields so the SAME test file compiled red (pre) and green (post).
+  const options = {
+    cwd: '/tmp',
+    uiEventPort: session,
+    commandEffectQueue: {
+      enqueueEffects: () => undefined,
+      drain: () => undefined,
+      clear: () => undefined,
+    },
+    addEntry: vi.fn(),
+    baseHandleSubmit: spies.baseHandleSubmit,
+    setSessionName: spies.setSessionName,
+    setStatusLineSettings: vi.fn(),
+    refreshStatusLineSettings: spies.refreshStatusLineSettings,
+    refreshAppearanceSettings: spies.refreshAppearanceSettings,
+    showSessionPickerOnStart: false,
+    openAgentSwitcher: spies.openAgentSwitcher,
+  } as unknown as IUseSideEffectsOptions;
+
+  function Probe(): React.ReactElement {
+    const state = useSideEffects(options);
+    resultRef.current = state;
+    return (
+      <Text>
+        {`plugin:${state.showPluginTUI ? 1 : 0} settings:${state.showTransportTUI ? 1 : 0} picker:${state.showSessionPicker ? 1 : 0}`}
+      </Text>
+    );
+  }
+
+  const instance = render(
+    <TuiCliAdapterProvider value={fakeCliAdapter(() => ({}))}>
+      <Probe />
+    </TuiCliAdapterProvider>,
+  );
+
+  return {
+    session,
+    result: () => {
+      if (!resultRef.current) throw new Error('useSideEffects result not captured');
+      return resultRef.current;
+    },
+    lastFrame: instance.lastFrame,
+    unmount: instance.unmount,
+    spies,
+  };
+}
+
+describe('ui_intent → TUI screens (requester-routed, CMD-004 Stage C)', () => {
+  it('show-settings with the owner requester opens the settings screen', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', { intent: { type: 'show-settings' }, requesterDriverId: 'owner' });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('settings:1'));
+    h.unmount();
+  });
+
+  it('show-plugin-manager with the owner requester opens the plugin screen', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-plugin-manager' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('plugin:1'));
+    h.unmount();
+  });
+
+  it('show-session-picker with the owner requester opens the session picker', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-session-picker' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => (h.lastFrame() ?? '').includes('picker:1'));
+    h.unmount();
+  });
+
+  it('show-agent-switcher with the owner requester invokes the switcher callback', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-agent-switcher' },
+      requesterDriverId: 'owner',
+    });
+    await waitUntil(() => h.spies.openAgentSwitcher.mock.calls.length === 1);
+    h.unmount();
+  });
+
+  it('an intent stamped with ANOTHER surface driver id is ignored (requester-routed)', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-settings' },
+      requesterDriverId: 'device-remote-1',
+    });
+    h.session.emit('ui_intent', {
+      intent: { type: 'show-agent-switcher' },
+      requesterDriverId: 'device-remote-1',
+    });
+    // Give the (wrong) render a chance to happen, then assert it did not.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(h.lastFrame()).toContain('settings:0');
+    expect(h.spies.openAgentSwitcher).not.toHaveBeenCalled();
+    h.unmount();
+  });
+
+  it('an unattributed intent (no requester id) is ignored by this surface', async () => {
+    const h = mountHarness();
+    h.session.emit('ui_intent', { intent: { type: 'show-settings' } });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(h.lastFrame()).toContain('settings:0');
+    h.unmount();
+  });
+
+  it('unmounting unsubscribes the ui_intent and session_renamed listeners', async () => {
+    const h = mountHarness();
+    const expected = Object.entries(TUI_SESSION_EVENT_CLASSIFICATION)
+      .filter(([, classification]) => classification === 'react-side-effect')
+      .map(([event]) => event)
+      .sort();
+    await waitUntil(() => h.session.subscribedEvents().sort().join() === expected.join());
+    h.unmount();
+    await waitUntil(() => h.session.subscribedEvents().length === 0);
+  });
+});
+
+describe('session_renamed broadcast → TUI title (CMD-004 Stage C / TC-10)', () => {
+  it('updates the session name from the broadcast without mutating the session itself', async () => {
+    const h = mountHarness();
+    h.session.emit('session_renamed', { name: 'Renamed via broadcast' });
+    await waitUntil(() => h.spies.setSessionName.mock.calls.length === 1);
+    expect(h.spies.setSessionName).toHaveBeenCalledWith('Renamed via broadcast');
+    // Pure renderer: the TUI reflects the host-executed rename; it never performs it.
+    expect(h.session.setName).not.toHaveBeenCalled();
+    h.unmount();
+  });
+});
+
+describe('statusline refresh-on-result (CMD-004 Stage C)', () => {
+  it('re-reads statusline settings after a slash-command result arrives', async () => {
+    const h = mountHarness();
+    await h.result().handleSubmit('/statusline off');
+    expect(h.spies.baseHandleSubmit).toHaveBeenCalledWith('/statusline off');
+    expect(h.spies.refreshStatusLineSettings).toHaveBeenCalledTimes(1);
+    // SCREEN-2002: the appearance is re-read on the same signal — a `/theme` result has already
+    // been written to the settings document by the host when this fires.
+    expect(h.spies.refreshAppearanceSettings).toHaveBeenCalledTimes(1);
+    h.unmount();
+  });
+
+  it('does not re-read for a plain (non-command) submit', async () => {
+    const h = mountHarness();
+    await h.result().handleSubmit('hello there');
+    expect(h.spies.refreshStatusLineSettings).not.toHaveBeenCalled();
+    expect(h.spies.refreshAppearanceSettings).not.toHaveBeenCalled();
+    h.unmount();
+  });
+});
+
+describe('useStatusLineSettings exposes a from-disk refresh', () => {
+  it('refresh() re-reads the persisted settings document', async () => {
+    let doc: Record<string, TUniversalValue> = { statusline: { enabled: true, gitBranch: true } };
+    const adapter = fakeCliAdapter(() => doc);
+    const captured: {
+      settings: { enabled: boolean; gitBranch: boolean } | null;
+      refresh: (() => void) | null;
+    } = { settings: null, refresh: null };
+
+    function Probe(): React.ReactElement {
+      const [settings, refresh] = useStatusLineSettings();
+      captured.settings = settings;
+      captured.refresh = refresh as unknown as () => void;
+      return <Text>{`enabled:${settings.enabled ? 1 : 0}`}</Text>;
+    }
+
+    const instance = render(
+      <TuiCliAdapterProvider value={adapter}>
+        <Probe />
+      </TuiCliAdapterProvider>,
+    );
+    await waitUntil(() => (instance.lastFrame() ?? '').includes('enabled:1'));
+
+    // The HOST persisted a patch (Stage B applies it via the settings adapter); the TUI refreshes.
+    doc = { statusline: { enabled: false, gitBranch: true } };
+    captured.refresh?.();
+    await waitUntil(() => (instance.lastFrame() ?? '').includes('enabled:0'));
+    expect(captured.settings?.enabled).toBe(false);
+    instance.unmount();
+  });
+});

package/src/__tests__/wave-text.test.tsx

@@ -0,0 +1,133 @@
+/**
+ * SCREEN-006 WaveText token-sourcing tests.
+ *
+ * WaveText's color ramp comes from the resolved theme's motion tokens (its cadence is its own) in
+ * `src/theme/built-in-themes.ts` (not component-private literals), and the gated/static
+ * frame must use the canonical muted token. Reduced-motion behavior is
+ * re-asserted against the token source: when `isInteractiveColorTerminal()` is
+ * false there is no interval and no color churn.
+ */
+import chalk from 'chalk';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import WaveText from '../WaveText.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+import { DARK_THEME } from '../theme/built-in-themes.js';
+import { foreground } from '../theme/index.js';
+
+/** Cadence is not themed; the component owns it (SCREEN-2002). */
+const WAVE_INTERVAL_MS = 400;
+
+const gateMock = vi.hoisted(() => ({ value: true }));
+
+vi.mock('../terminal-capabilities.js', () => ({
+  isInteractiveColorTerminal: (): boolean => gateMock.value,
+}));
+
+/** Extract every SGR open-sequence used in a frame (e.g. "38;2;85;85;85"). */
+function sgrCodes(frame: string): string[] {
+  // eslint-disable-next-line no-control-regex -- asserting on raw SGR escape bytes by design
+  return [...frame.matchAll(/\x1b\[([0-9;]+)m/g)].map((m) => m[1]);
+}
+
+/** The SGR open code chalk emits for a color, at the level ink uses in this env. */
+function chalkOpenCodes(colorize: (s: string) => string): string[] {
+  return sgrCodes(colorize('x'));
+}
+
+const ORIGINAL_CHALK_LEVEL = chalk.level;
+
+beforeAll(() => {
+  // Pin color bytes regardless of the test process's TTY detection (cjk-fallback precedent).
+  chalk.level = 3;
+});
+
+afterAll(() => {
+  chalk.level = ORIGINAL_CHALK_LEVEL;
+});
+
+afterEach(() => {
+  gateMock.value = true;
+  vi.useRealTimers();
+});
+
+describe('WaveText motion tokens (SCREEN-006)', () => {
+  it('animated frames draw only from the theme’s wave ramp', () => {
+    gateMock.value = true;
+    const allowed = new Set<string>(['39', '0']);
+    for (const stop of DARK_THEME.motion.wave) {
+      for (const code of chalkOpenCodes((s) => chalk.hex(stop)(s))) {
+        allowed.add(code);
+      }
+    }
+
+    const { lastFrame, unmount } = render(<WaveText text="Thinking" />);
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    const used = sgrCodes(frame);
+    expect(used.length).toBeGreaterThan(0);
+    const outside = used.filter((code) => !allowed.has(code));
+    expect(outside).toEqual([]);
+  });
+
+  it('gated/static frame renders with the theme’s muted token and no color churn', () => {
+    gateMock.value = false;
+    vi.useFakeTimers();
+
+    const { lastFrame, unmount } = render(<WaveText text="Thinking" />);
+    const first = lastFrame() ?? '';
+
+    // The muted token (not a wave hex stop) styles the static frame.
+    const mutedCodes = chalkOpenCodes((s) => foreground(DARK_THEME.colors.text.muted)(s));
+    for (const code of mutedCodes) {
+      expect(first).toContain(`\u001b[${code}m`);
+    }
+
+    // No interval ⇒ no motion: advancing time produces the identical frame.
+    vi.advanceTimersByTime(WAVE_INTERVAL_MS * 5);
+    const later = lastFrame() ?? '';
+    unmount();
+    expect(later).toBe(first);
+  });
+});
+
+/**
+ * CLI-2004 TC-19 — a spinner is a repaint per frame, and a repaint is an announcement. In the mode
+ * the text is written once and no interval is ever scheduled.
+ */
+describe('CLI-2004 TC-19: WaveText in screen-reader mode', () => {
+  it('renders its text once and schedules no interval', () => {
+    gateMock.value = true; // the colour gate is OPEN — the mode alone must stop the animation
+    vi.useFakeTimers();
+
+    const { lastFrame, unmount } = render(
+      <ScreenReaderProvider enabled={true}>
+        <WaveText text="Thinking" />
+      </ScreenReaderProvider>,
+    );
+    const first = lastFrame() ?? '';
+
+    // No pending timer at all — not merely a frame that happens to look the same.
+    expect(vi.getTimerCount()).toBe(0);
+
+    vi.advanceTimersByTime(WAVE_INTERVAL_MS * 5);
+    const later = lastFrame() ?? '';
+    unmount();
+
+    expect(first).toContain('Thinking');
+    expect(later).toBe(first);
+    expect(sgrCodes(first).filter((code) => code !== '0' && code !== '39')).toEqual([]);
+  });
+
+  it('leaves the 400 ms ramp exactly as it is outside the mode', () => {
+    gateMock.value = true;
+    vi.useFakeTimers();
+
+    const { unmount } = render(<WaveText text="Thinking" />);
+    expect(vi.getTimerCount()).toBeGreaterThan(0);
+    unmount();
+  });
+});

package/src/app-banner.tsx

@@ -0,0 +1,42 @@
+/**
+ * The startup banner, committed once to the terminal scrollback.
+ *
+ * Extracted from `App.tsx` under CLI-2004: the art is ASCII, not box-drawing, so a
+ * no-box-drawing sweep passes over it unchanged — it needs its own suppression AND its own
+ * assertion, and neither is reviewable while the glyphs live inline in a 600-line component.
+ * `BANNER_GLYPHS` is the set a test asserts is absent in screen-reader mode.
+ */
+
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+/** The ASCII art itself. */
+export const BANNER_ART = `
+  ____   ___  ____   ___ _____  _
+ |  _ \\ / _ \\| __ ) / _ \\_   _|/ \\
+ | |_) | | | |  _ \\| | | || | / _ \\
+ |  _ <| |_| | |_) | |_| || |/ ___ \\
+ |_| \\_\\\\___/|____/ \\___/ |_/_/   \\_\\
+`;
+
+/**
+ * The characters the art is drawn from. None is a box-drawing character, which is exactly why the
+ * banner needs a suppression test of its own.
+ */
+export const BANNER_GLYPHS: readonly string[] = ['_', '|', '\\', '/', '<'];
+
+/** The banner as it is committed to scrollback: the art plus the version line. */
+export function AppBanner({ version }: { version: string }): React.ReactElement {
+  const palette = usePalette();
+  return (
+    <Box flexDirection="column" paddingX={1} marginBottom={1}>
+      <Text color={palette.text.accent} bold>
+        {BANNER_ART}
+      </Text>
+      <Text dimColor> v{version}</Text>
+    </Box>
+  );
+}

package/src/app-static-items.ts

@@ -0,0 +1,35 @@
+/**
+ * SCREEN-010 / CLI-2004 — what gets committed to the terminal's native scrollback.
+ *
+ * The App renders exactly this list inside a single Ink `<Static>`, so each item is written once and
+ * never repainted. Building the list is a pure function so the ONE decision that varies — whether
+ * the startup banner is committed at all — is assertable without mounting the App.
+ */
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+
+/** A committed item: the startup banner, or one conversation entry. */
+export type TStaticItem =
+  | { readonly kind: 'banner'; readonly version: string }
+  | { readonly kind: 'entry'; readonly entry: IHistoryEntry };
+
+export interface IBuildStaticItemsInputs {
+  history: readonly IHistoryEntry[];
+  version: string | undefined;
+  /**
+   * Screen-reader mode. The banner is ASCII art with no spoken meaning — a reader announces it
+   * character by character before the session has said anything — so the mode omits the item
+   * entirely rather than styling it differently.
+   */
+  screenReader: boolean;
+}
+
+const FALLBACK_VERSION = '0.0.0';
+
+/** Build the `<Static>` item list. */
+export function buildStaticItems(inputs: IBuildStaticItemsInputs): TStaticItem[] {
+  const banner: TStaticItem[] = inputs.screenReader
+    ? []
+    : [{ kind: 'banner', version: inputs.version ?? FALLBACK_VERSION }];
+  return [...banner, ...inputs.history.map((entry): TStaticItem => ({ kind: 'entry', entry }))];
+}

package/src/app-view-model.ts

@@ -0,0 +1,136 @@
+import type { TStaticItem } from './app-static-items.js';
+import type { IAppThemeViewModel } from './hooks/useAppThemeState.js';
+import type { IInputAreaHistorySearch } from './hooks/useInputAreaHistorySearch.js';
+import type { ITuiCommandQueryPort } from './tui-app-channel-port.js';
+import type { ITuiSessionEventNotice } from './tui-session-events.js';
+import type { IPendingPermissionRequest } from './types.js';
+import type {
+  IActionRequest,
+  IHistoryEntry,
+  TActionResponse,
+  TModelEffortSelection,
+  TPermissionMode,
+} from '@robota-sdk/agent-core';
+import type {
+  ICommandPluginAdapter,
+  IStatusLineCommandSettings,
+} from '@robota-sdk/agent-interface-command';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  IResumableSessionSummary,
+  IToolState,
+} from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+export interface IAppViewModel {
+  readonly staticItems: TStaticItem[];
+  readonly handoffSuspended: boolean;
+  readonly updateNotice: string | undefined;
+  readonly coordinationError: string | undefined;
+  readonly coordinationPending: boolean;
+  readonly sessionEventNotices: readonly ITuiSessionEventNotice[];
+  readonly isShuttingDown: boolean;
+  readonly stream: {
+    readonly text: string;
+    readonly activeTools: readonly IToolState[];
+    readonly isThinking: boolean;
+    readonly isStalled: boolean;
+    readonly lastErrorMessage: string | null;
+  };
+  readonly background: IAppBackgroundViewModel;
+  readonly permissionRequest: IPendingPermissionRequest | null;
+  readonly pendingUserAction: IActionRequest | null;
+  readonly resolveUserAction: (request: IActionRequest, response: TActionResponse) => void;
+  readonly plugin: IAppPluginViewModel;
+  readonly transport: IAppTransportViewModel;
+  readonly sessionPicker: IAppSessionPickerViewModel;
+  /** SCREEN-2002: the live theme, the resolved motion setting, and the picker over them. */
+  readonly theme: IAppThemeViewModel;
+  readonly contextPercentage: number;
+  readonly input: IAppInputViewModel;
+  readonly status: IAppStatusViewModel;
+}
+
+export type { IAppThemePickerViewModel, IAppThemeViewModel } from './hooks/useAppThemeState.js';
+
+export interface IAppBackgroundViewModel {
+  readonly entries: IExecutionWorkspaceEntry[];
+  readonly focusedIndex: number | null;
+  readonly selectedEntry: IExecutionWorkspaceEntry | undefined;
+  readonly detail: {
+    readonly page: IExecutionDetailPage | null;
+    readonly loading: boolean;
+    readonly error: string | undefined;
+  };
+  readonly switcherVisible: boolean;
+  readonly snapshot: IExecutionWorkspaceSnapshot | null;
+  readonly selectedEntryId: string | undefined;
+  readonly select: (entryId: string) => void;
+  readonly closeSwitcher: () => void;
+  readonly attachToFork: (entry: IExecutionWorkspaceEntry) => void;
+}
+
+export interface IAppPluginViewModel {
+  readonly visible: boolean;
+  readonly callbacks: ICommandPluginAdapter;
+  readonly close: () => void;
+  readonly addMessage: (content: string) => void;
+}
+
+export interface IAppTransportViewModel {
+  readonly visible: boolean;
+  readonly registry: ITransportRegistryView | undefined;
+  readonly close: () => void;
+}
+
+export interface IAppSessionPickerViewModel {
+  readonly visible: boolean;
+  readonly sessions: readonly IResumableSessionSummary[];
+  readonly select: (sessionId: string) => void;
+  readonly cancel: () => void;
+}
+
+export interface IAppInputViewModel {
+  /** FLOW-2006: the deep link's prefill, present only until the composer takes it. */
+  readonly initialValue?: string | undefined;
+  /** Called by the composer the first time it seeds itself, so a remount does not re-seed. */
+  readonly consumeInitialValue?: (() => void) | undefined;
+  /** True while the composer's text is the one a deep link supplied. */
+  readonly externalPromptOrigin?: boolean | undefined;
+  readonly submit: (input: string) => Promise<void>;
+  readonly cancelQueue: () => void;
+  readonly disabled: boolean;
+  readonly queueCancellationDisabled: boolean;
+  readonly isAborting: boolean;
+  readonly pendingPrompt: string | null;
+  readonly pendingCount: number;
+  readonly commandQueryPort: ITuiCommandQueryPort;
+  readonly sessionName: string | undefined;
+  readonly history: readonly IHistoryEntry[];
+  readonly focusBackgroundList: () => void;
+  /** SCREEN-1993: the stored-prompt search surface; absent ⇒ the feature is off. */
+  readonly historySearch: IInputAreaHistorySearch | undefined;
+}
+
+export interface IAppStatusViewModel {
+  readonly cwd: string;
+  readonly permissionMode: TPermissionMode;
+  readonly modelId: string | undefined;
+  readonly providerType: string | undefined;
+  readonly sessionId: string;
+  readonly isThinking: boolean;
+  readonly activeToolCount: number;
+  readonly activeBackgroundTaskCount: number;
+  readonly hasPendingPrompt: boolean;
+  readonly contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  readonly sessionName: string | undefined;
+  readonly settings: IStatusLineCommandSettings;
+  readonly activeAgentLabel: string | undefined;
+  readonly activePresetId: string | undefined;
+  readonly effort: TModelEffortSelection | undefined;
+  readonly gitRefreshToken: number;
+}