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

package/src/attention/__tests__/attention-tracker.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AttentionTracker, DEFAULT_IDLE_THRESHOLD_MS } from '../attention-tracker.js';
+
+function tracker(options: { focusReporting: boolean }) {
+  const events: string[] = [];
+  const instance = new AttentionTracker({
+    focusReporting: options.focusReporting,
+    now: () => Date.now(),
+  });
+  instance.subscribe((change) => events.push(`${change.kind}@${change.at}`));
+  return { instance, events };
+}
+
+describe('AttentionTracker (SCREEN-1992 TC-01)', () => {
+  it('with focus reporting, focus-out and focus-in emit once per transition and the idle source is inert', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: true });
+      instance.start();
+      expect(instance.attended).toBe(true);
+      // Requested is not confirmed: until a focus event arrives the idle source decides.
+      expect(instance.source).toBe('idle');
+      instance.focusOut();
+      expect(instance.source).toBe('focus');
+      instance.focusOut();
+      expect(instance.attended).toBe(false);
+      expect(events).toEqual(['lost@2026-01-01T00:00:00.000Z']);
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 3);
+      instance.keystroke(); // a keystroke while focus reporting is authoritative changes nothing
+      expect(instance.attended).toBe(false);
+      vi.setSystemTime(new Date('2026-01-01T00:20:00.000Z'));
+      instance.focusIn();
+      instance.focusIn();
+      expect(events).toEqual([
+        'lost@2026-01-01T00:00:00.000Z',
+        'returned@2026-01-01T00:20:00.000Z',
+      ]);
+      instance.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('with focus reporting requested but never answered, the idle source still runs', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: true });
+      instance.start();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS);
+      expect(instance.attended).toBe(false);
+      expect(instance.source).toBe('idle');
+      instance.keystroke();
+      expect(instance.attended).toBe(true);
+      expect(events.map((event) => event.split('@')[0])).toEqual(['lost', 'returned']);
+      // The first focus event disarms the idle source for good.
+      instance.focusIn();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 2);
+      expect(instance.attended).toBe(true);
+      expect(instance.source).toBe('focus');
+      instance.dispose();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('refuses a focus event when focus reporting is off', () => {
+    const { instance } = tracker({ focusReporting: false });
+    expect(() => instance.focusIn()).toThrow(/focus reporting is off/u);
+  });
+
+  it('without focus reporting, the idle threshold marks unattended and the next keystroke marks attended', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+      const { instance, events } = tracker({ focusReporting: false });
+      expect(instance.source).toBe('idle');
+      instance.start();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS - 1);
+      instance.keystroke(); // activity resets the idle clock
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS - 1);
+      expect(instance.attended).toBe(true);
+      expect(events).toEqual([]);
+      vi.advanceTimersByTime(1);
+      expect(instance.attended).toBe(false);
+      expect(events).toHaveLength(1);
+      expect(events[0]).toMatch(/^lost@/);
+      instance.keystroke();
+      expect(instance.attended).toBe(true);
+      expect(events).toHaveLength(2);
+      expect(events[1]).toMatch(/^returned@/);
+      instance.keystroke();
+      expect(events).toHaveLength(2);
+      instance.dispose();
+      vi.advanceTimersByTime(DEFAULT_IDLE_THRESHOLD_MS * 2);
+      expect(events).toHaveLength(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/attention/__tests__/countdown.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatCountdown } from '../countdown.js';
+
+describe('formatCountdown (SCREEN-1992 TC-04)', () => {
+  it('renders seconds, minutes and hours against the given now, and "now" once due', () => {
+    const now = new Date('2026-01-01T00:00:00.000Z');
+    expect(formatCountdown('2026-01-01T00:00:59.000Z', now)).toBe('in 59s');
+    expect(formatCountdown('2026-01-01T00:04:59.000Z', now)).toBe('in 4m 59s');
+    expect(formatCountdown('2026-01-01T02:05:00.000Z', now)).toBe('in 2h 5m');
+    expect(formatCountdown('2026-01-01T00:00:00.000Z', now)).toBe('now');
+    expect(formatCountdown('2025-12-31T23:59:00.000Z', now)).toBe('now');
+    expect(formatCountdown('not-a-date', now)).toBeUndefined();
+  });
+});

package/src/attention/__tests__/focus-input-filter.test.ts

@@ -0,0 +1,93 @@
+import { EventEmitter } from 'node:events';
+
+import { describe, expect, it, vi } from 'vitest';
+import korean from '../../__tests__/__fixtures__/korean-text.json';
+
+import { filterFocusSequences, FocusReportingStdin } from '../focus-input-filter.js';
+import { createFocusReportingWriter } from '../../terminal-focus-reporting.js';
+
+class FakeStdin extends EventEmitter {
+  isTTY = true;
+  setRawMode = vi.fn();
+  ref = vi.fn();
+  unref = vi.fn();
+}
+
+function collect(stream: FocusReportingStdin): Buffer[] {
+  const chunks: Buffer[] = [];
+  stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+  return chunks;
+}
+
+describe('focus input filter (SCREEN-1992 TC-06)', () => {
+  it('strips CSI I / CSI O only while negotiated and forwards everything else byte-identical', () => {
+    const negotiated = filterFocusSequences(Buffer.from('a\x1b[Ob\x1b[Ic'), true);
+    expect(negotiated.forwarded.toString()).toBe('abc');
+    expect(negotiated).toMatchObject({ focusIn: 1, focusOut: 1 });
+
+    const passthrough = filterFocusSequences(Buffer.from('a\x1b[Ob'), false);
+    expect(passthrough.forwarded.toString()).toBe('a\x1b[Ob');
+    expect(passthrough).toMatchObject({ focusIn: 0, focusOut: 0 });
+
+    // A split escape sequence and a bracketed paste are Ink's to parse — untouched.
+    expect(filterFocusSequences(Buffer.from('\x1b['), true).forwarded.toString()).toBe('\x1b[');
+    expect(filterFocusSequences(Buffer.from('A'), true).forwarded.toString()).toBe('A');
+    const paste = '\x1b[200~pasted \x1b[I text\x1b[201~';
+    expect(filterFocusSequences(Buffer.from(paste), false).forwarded.toString()).toBe(paste);
+    const utf8 = Buffer.from(`${korean.hangulWord}\x1b[O😀`);
+    expect(filterFocusSequences(utf8, true).forwarded.toString()).toBe(`${korean.hangulWord}😀`);
+  });
+
+  it('proxies stdin: reports focus and keystrokes, forwards isTTY/setRawMode/ref/unref', async () => {
+    const source = new FakeStdin();
+    const hooks = {
+      negotiated: () => true,
+      onFocusIn: vi.fn(),
+      onFocusOut: vi.fn(),
+      onKeystroke: vi.fn(),
+    };
+    const proxy = new FocusReportingStdin(source, hooks);
+    const chunks = collect(proxy);
+    source.emit('data', Buffer.from('\x1b[O'));
+    source.emit('data', Buffer.from('x\x1b[I'));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(hooks.onFocusOut).toHaveBeenCalledTimes(1);
+    expect(hooks.onFocusIn).toHaveBeenCalledTimes(1);
+    expect(hooks.onKeystroke).toHaveBeenCalledTimes(1);
+    expect(Buffer.concat(chunks).toString()).toBe('x');
+
+    expect(proxy.isTTY).toBe(true);
+    proxy.setRawMode(true);
+    proxy.ref();
+    proxy.unref();
+    expect(source.setRawMode).toHaveBeenCalledWith(true);
+    expect(source.ref).toHaveBeenCalledTimes(1);
+    expect(source.unref).toHaveBeenCalledTimes(1);
+
+    proxy.detach();
+    source.emit('data', Buffer.from('y'));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(Buffer.concat(chunks).toString()).toBe('x');
+  });
+
+  it('writes DECSET 1004 only when the gate allows, and DECRST once on disable', () => {
+    const written: string[] = [];
+    let supported = false;
+    const writer = createFocusReportingWriter({
+      supported: () => supported,
+      write: (text) => written.push(text),
+    });
+    writer.enable();
+    expect(writer.negotiated).toBe(false);
+    expect(written).toEqual([]);
+    supported = true;
+    writer.enable();
+    writer.enable();
+    expect(writer.negotiated).toBe(true);
+    expect(written).toEqual(['\x1b[?1004h']);
+    writer.disable();
+    writer.disable();
+    expect(writer.negotiated).toBe(false);
+    expect(written).toEqual(['\x1b[?1004h', '\x1b[?1004l']);
+  });
+});

package/src/attention/__tests__/interval-recap.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { IntervalRecap, RECAP_MAX_WIDTH } from '../interval-recap.js';
+
+describe('IntervalRecap (SCREEN-1992 TC-02)', () => {
+  it('counts turns by source, needs-input requests and terminal entries, and yields one line on return', () => {
+    const recap = new IntervalRecap();
+    // Attended: nothing is counted.
+    recap.turnSource('user');
+    recap.turnCompleted();
+    expect(recap.onReturned('2026-01-01T00:00:00.000Z')).toBeUndefined();
+
+    // Already terminal before the interval: old news, never counted.
+    recap.entryState('task:old', 'completed');
+    recap.onLost('2026-01-01T00:00:00.000Z');
+    recap.entryState('task:old', 'completed');
+    recap.turnSource('agent-wakeup');
+    recap.turnCompleted();
+    recap.turnSource('user');
+    recap.turnCompleted();
+    recap.needsInput();
+    recap.entryState('task:1', 'working');
+    recap.entryState('task:1', 'failed');
+    recap.entryState('task:1', 'failed'); // same terminal state twice counts once
+    recap.entryState('task:2', 'completed');
+    recap.entryState('task:3', 'completed');
+    recap.entryState('task:3', 'working'); // left the terminal state again: dropped
+    recap.error();
+    const line = recap.onReturned('2026-01-01T00:12:00.000Z');
+    expect(line).toBe(
+      'While away 12m: 2 turns finished (1 wake) · 1 needs input · 1 completed · 1 failed · 1 error',
+    );
+    // A second return without a new interval yields nothing.
+    expect(recap.onReturned('2026-01-01T00:13:00.000Z')).toBeUndefined();
+  });
+
+  it('yields nothing for an empty interval and bounds a long line', () => {
+    const recap = new IntervalRecap();
+    recap.onLost('2026-01-01T00:00:00.000Z');
+    expect(recap.onReturned('2026-01-01T01:00:00.000Z')).toBeUndefined();
+
+    recap.entryState('task:seed', 'working'); // a snapshot has been seen: the baseline is known
+    recap.onLost('2026-01-01T02:00:00.000Z');
+    for (let i = 0; i < 1000; i += 1) recap.entryState(`task:${i}`, 'completed');
+    const line = recap.onReturned('2026-01-01T03:30:00.000Z')!;
+    expect(line.length).toBeLessThanOrEqual(RECAP_MAX_WIDTH);
+    expect(line).toContain('While away 1h 30m');
+  });
+});

package/src/attention/attention-coordinator.ts

@@ -0,0 +1,71 @@
+import { IntervalRecap } from './interval-recap.js';
+
+import type { IAttentionSource } from './attention-tracker.js';
+import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * SCREEN-1992: joins the attention level to the recap accumulator for one channel.
+ *
+ * The tracker outlives channels (it is the terminal's), the recap belongs to the session being
+ * shown; the coordinator subscribes for the channel's lifetime and pushes each recap line into the
+ * channel's notice store. It lives here rather than in `tui-state-manager.ts` (at its line ceiling).
+ */
+export interface IAttentionCoordinatorOptions {
+  readonly source: IAttentionSource;
+  readonly onRecap: (line: string) => void;
+  readonly now?: () => number;
+}
+
+export class AttentionCoordinator {
+  private readonly recap = new IntervalRecap();
+  private unsubscribe: (() => void) | undefined;
+  private readonly now: () => number;
+
+  constructor(private readonly options: IAttentionCoordinatorOptions) {
+    this.now = options.now ?? Date.now;
+  }
+
+  wire(): void {
+    if (this.unsubscribe !== undefined) return;
+    // A channel created while the user is already away starts its interval now.
+    if (!this.options.source.attended) this.recap.onLost(new Date(this.now()).toISOString());
+    this.unsubscribe = this.options.source.subscribe((change) => {
+      if (change.kind === 'lost') {
+        this.recap.onLost(change.at);
+        return;
+      }
+      const line = this.recap.onReturned(change.at);
+      if (line !== undefined) this.options.onRecap(line);
+    });
+  }
+
+  unwire(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+
+  onTurnSource = (source: string): void => {
+    this.recap.turnSource(source);
+  };
+
+  onComplete = (): void => {
+    this.recap.turnCompleted();
+  };
+
+  onError = (): void => {
+    this.recap.error();
+  };
+
+  onNeedsInput = (): void => {
+    this.recap.needsInput();
+  };
+
+  onWorkspaceSnapshot = (snapshot: IExecutionWorkspaceSnapshot): void => {
+    for (const entry of snapshot.entries) {
+      // The main thread's turns are counted from `complete`; its idle `completed` is not an event.
+      if (entry.kind === 'main_thread') continue;
+      this.recap.entryState(entry.id, entry.state);
+    }
+    this.recap.snapshotComplete();
+  };
+}

package/src/attention/attention-tracker.ts

@@ -0,0 +1,124 @@
+/**
+ * SCREEN-1992: whether the user is at the terminal.
+ *
+ * Two sources feed one boolean. Focus reporting (DECSET 1004) was REQUESTED, not confirmed — a
+ * terminal that does not implement the mode discards the request and never answers — so focus
+ * becomes authoritative only once the first `CSI I`/`CSI O` has actually arrived; from then on
+ * keystrokes carry no attention meaning. Until then, and wherever the mode is off, the only signal
+ * is input: silence past the idle threshold means "away", the next keystroke means "back".
+ */
+import { MS_PER_MINUTE } from './time-units.js';
+
+const DEFAULT_IDLE_THRESHOLD_MINUTES = 5;
+export const DEFAULT_IDLE_THRESHOLD_MS = DEFAULT_IDLE_THRESHOLD_MINUTES * MS_PER_MINUTE;
+
+export type TAttentionChangeKind = 'lost' | 'returned';
+
+export interface IAttentionChange {
+  readonly kind: TAttentionChangeKind;
+  /** ISO timestamp of the transition, from the injected clock. */
+  readonly at: string;
+}
+
+export type TAttentionListener = (change: IAttentionChange) => void;
+
+/** What a consumer of attention sees: the level, and every transition. */
+export interface IAttentionSource {
+  readonly attended: boolean;
+  /** Which source decides the level right now — recorded so a degraded run is never a silent default. */
+  readonly source: 'focus' | 'idle';
+  subscribe(listener: TAttentionListener): () => void;
+}
+
+export interface IAttentionTrackerOptions {
+  /** Whether DECSET 1004 was requested; the first focus event is what makes it authoritative. */
+  readonly focusReporting: boolean;
+  readonly now: () => number;
+  readonly idleThresholdMs?: number;
+}
+
+export class AttentionTracker implements IAttentionSource {
+  private attendedState = true;
+  private focusObserved = false;
+  private readonly listeners = new Set<TAttentionListener>();
+  private idleTimer: ReturnType<typeof setTimeout> | undefined;
+  private readonly idleThresholdMs: number;
+
+  constructor(private readonly options: IAttentionTrackerOptions) {
+    this.idleThresholdMs = options.idleThresholdMs ?? DEFAULT_IDLE_THRESHOLD_MS;
+  }
+
+  get attended(): boolean {
+    return this.attendedState;
+  }
+
+  get source(): 'focus' | 'idle' {
+    return this.focusObserved ? 'focus' : 'idle';
+  }
+
+  subscribe(listener: TAttentionListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Arms the idle fallback; the first focus event disarms it for good. */
+  start(): void {
+    if (this.focusObserved) return;
+    this.armIdleTimer();
+  }
+
+  focusIn(): void {
+    this.observeFocus();
+    this.transition(true);
+  }
+
+  focusOut(): void {
+    this.observeFocus();
+    this.transition(false);
+  }
+
+  /** Any key the user pressed. Only the idle source reads it. */
+  keystroke(): void {
+    if (this.focusObserved) return;
+    this.transition(true);
+    this.armIdleTimer();
+  }
+
+  private observeFocus(): void {
+    if (!this.options.focusReporting) {
+      throw new Error('AttentionTracker: a focus event arrived although focus reporting is off.');
+    }
+    if (this.focusObserved) return;
+    this.focusObserved = true;
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = undefined;
+  }
+
+  dispose(): void {
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = undefined;
+    this.listeners.clear();
+  }
+
+  private armIdleTimer(): void {
+    if (this.idleTimer !== undefined) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = undefined;
+      this.transition(false);
+    }, this.idleThresholdMs);
+    // Never keep the process alive for an attention timer.
+    if (typeof this.idleTimer === 'object' && 'unref' in this.idleTimer) this.idleTimer.unref();
+  }
+
+  private transition(attended: boolean): void {
+    if (this.attendedState === attended) return;
+    this.attendedState = attended;
+    const change: IAttentionChange = {
+      kind: attended ? 'returned' : 'lost',
+      at: new Date(this.options.now()).toISOString(),
+    };
+    for (const listener of this.listeners) listener(change);
+  }
+}

package/src/attention/countdown.ts

@@ -0,0 +1,24 @@
+import {
+  MINUTES_PER_HOUR,
+  MS_PER_SECOND,
+  SECONDS_PER_HOUR,
+  SECONDS_PER_MINUTE,
+} from './time-units.js';
+
+/**
+ * SCREEN-1992: the time until a sleeping schedule fires, rendered against a given clock so the
+ * row can tick once a second without the projection changing.
+ */
+export function formatCountdown(nextFireAt: string, now: Date): string | undefined {
+  const target = Date.parse(nextFireAt);
+  if (Number.isNaN(target)) return undefined;
+  const remainingMs = target - now.getTime();
+  if (remainingMs <= 0) return 'now';
+  const totalSeconds = Math.floor(remainingMs / MS_PER_SECOND);
+  const hours = Math.floor(totalSeconds / SECONDS_PER_HOUR);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE) % MINUTES_PER_HOUR;
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  if (hours > 0) return `in ${hours}h ${minutes}m`;
+  if (minutes > 0) return `in ${minutes}m ${seconds}s`;
+  return `in ${seconds}s`;
+}

package/src/attention/focus-input-filter.ts

@@ -0,0 +1,131 @@
+import { Readable } from 'node:stream';
+
+/**
+ * SCREEN-1992: the stdin proxy handed to Ink's `render({ stdin })`.
+ *
+ * Ink tokenizes `ESC [ I` as a keypress and every `useInput` listener would receive `[I`, so the
+ * composer would type it. The proxy sits in front of the real stdin, strips the two focus sequences
+ * while mode 1004 is negotiated, reports focus and keystrokes, and forwards every other byte
+ * unchanged — including a split escape sequence and a bracketed paste, which are Ink's to parse.
+ */
+const ESC = 0x1b;
+const FOCUS_IN = '\x1b[I';
+const FOCUS_OUT = '\x1b[O';
+
+export interface IFocusInputFilterResult {
+  /** The bytes Ink receives, byte-identical to the input apart from the stripped focus sequences. */
+  readonly forwarded: Buffer;
+  readonly focusIn: number;
+  readonly focusOut: number;
+}
+
+/** Pure: split one chunk into focus events and the bytes that remain. */
+export function filterFocusSequences(chunk: Buffer, negotiated: boolean): IFocusInputFilterResult {
+  if (!negotiated || !chunk.includes(ESC)) return { forwarded: chunk, focusIn: 0, focusOut: 0 };
+  const text = chunk.toString('latin1');
+  let focusIn = 0;
+  let focusOut = 0;
+  let forwarded = '';
+  let index = 0;
+  while (index < text.length) {
+    if (text.startsWith(FOCUS_IN, index)) {
+      focusIn += 1;
+      index += FOCUS_IN.length;
+    } else if (text.startsWith(FOCUS_OUT, index)) {
+      focusOut += 1;
+      index += FOCUS_OUT.length;
+    } else {
+      forwarded += text[index];
+      index += 1;
+    }
+  }
+  return { forwarded: Buffer.from(forwarded, 'latin1'), focusIn, focusOut };
+}
+
+export interface IFocusReportingStdinHooks {
+  /** Whether mode 1004 is currently negotiated; read per chunk so a handoff can flip it. */
+  readonly negotiated: () => boolean;
+  readonly onFocusIn: () => void;
+  readonly onFocusOut: () => void;
+  /** Any byte that was not a focus sequence. */
+  readonly onKeystroke: () => void;
+}
+
+type TStdinDataListener = (chunk: Buffer | string) => void;
+
+/** What ink 7.1.1 reads from the stream it is given (`App.js` input handling, `ink.js` kitty probe). */
+type TInkStdinSurface = Pick<
+  Readable,
+  'read' | 'setEncoding' | 'unshift' | 'on' | 'addListener' | 'removeListener'
+> & {
+  readonly isTTY: boolean;
+  // `tty.ReadStream` types these as returning itself; Ink discards the return value.
+  setRawMode(mode: boolean): TInkStdinSurface;
+  ref(): TInkStdinSurface;
+  unref(): TInkStdinSurface;
+};
+
+/** The subset of the real stdin the proxy touches (what `process.stdin` provides). */
+export interface IFocusReportingStdinSource {
+  readonly isTTY?: boolean;
+  on(event: 'data', listener: TStdinDataListener): void;
+  off(event: 'data', listener: TStdinDataListener): void;
+  setRawMode?: (mode: boolean) => void;
+  ref?: () => void;
+  unref?: () => void;
+}
+
+export class FocusReportingStdin extends Readable {
+  private readonly onData = (data: Buffer | string): void => {
+    const chunk = typeof data === 'string' ? Buffer.from(data) : data;
+    const result = filterFocusSequences(chunk, this.hooks.negotiated());
+    for (let i = 0; i < result.focusOut; i += 1) this.hooks.onFocusOut();
+    for (let i = 0; i < result.focusIn; i += 1) this.hooks.onFocusIn();
+    if (result.forwarded.length === 0) return;
+    this.hooks.onKeystroke();
+    this.push(result.forwarded);
+  };
+
+  constructor(
+    private readonly source: IFocusReportingStdinSource,
+    private readonly hooks: IFocusReportingStdinHooks,
+  ) {
+    super({ read() {} });
+    source.on('data', this.onData);
+  }
+
+  get isTTY(): boolean {
+    return this.source.isTTY === true;
+  }
+
+  setRawMode(mode: boolean): this {
+    this.source.setRawMode?.(mode);
+    return this;
+  }
+
+  ref(): this {
+    this.source.ref?.();
+    return this;
+  }
+
+  unref(): this {
+    this.source.unref?.();
+    return this;
+  }
+
+  /**
+   * Ink declares `stdin?: NodeJS.ReadStream` (a `tty.ReadStream`, which cannot be constructed
+   * without an fd) but touches only the members named in `TInkStdinSurface` — verified against ink
+   * 7.1.1's App and Ink classes. Assigning `this` to that surface is a typed check that every one of
+   * them exists here; the final narrowing is from the surface Ink reads to the type it declares.
+   */
+  asInkStdin(): NodeJS.ReadStream {
+    const surface: TInkStdinSurface = this;
+    return surface as NodeJS.ReadStream;
+  }
+
+  /** Detach from the underlying stdin; the proxy emits nothing afterwards. */
+  detach(): void {
+    this.source.off('data', this.onData);
+  }
+}