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

package/src/flows/cjk-text-deletion.ts

@@ -0,0 +1,53 @@
+/**
+ * CLI-2004 — deletion, and what was deleted.
+ *
+ * A reader announces the line it is on. When a whole word or the whole line disappears, the only
+ * thing it can say is what is LEFT — which is exactly the information you do not need. These helpers
+ * return the removed text alongside the new value so the input can say what went.
+ *
+ * Word and line deletion are added here as well as reported: the flow had only single-character
+ * backspace, so `Ctrl+W`/`Ctrl+U` previously fell through to the printable-input path.
+ *
+ * Extracted from `cjk-text-input-flow.ts` by responsibility — that module routes keystrokes, this
+ * one computes edits.
+ */
+
+/** The result of one deletion: the new buffer, the new cursor, and the text that was removed. */
+export interface ICjkDeletion {
+  value: string;
+  cursor: number;
+  deleted: string;
+}
+
+/** Remove the character before the cursor. `undefined` at the start of the buffer. */
+export function deleteCharBeforeCursor(value: string, cursor: number): ICjkDeletion | undefined {
+  if (cursor <= 0) return undefined;
+  return {
+    value: value.slice(0, cursor - 1) + value.slice(cursor),
+    cursor: cursor - 1,
+    deleted: value.slice(cursor - 1, cursor),
+  };
+}
+
+/**
+ * Remove the word before the cursor — trailing spaces first, then the run of non-space characters,
+ * which is the behaviour every shell's `Ctrl+W` has.
+ */
+export function deleteWordBeforeCursor(value: string, cursor: number): ICjkDeletion | undefined {
+  if (cursor <= 0) return undefined;
+  let start = cursor;
+  while (start > 0 && /\s/u.test(value[start - 1] ?? '')) start -= 1;
+  while (start > 0 && !/\s/u.test(value[start - 1] ?? '')) start -= 1;
+  if (start === cursor) return undefined;
+  return {
+    value: value.slice(0, start) + value.slice(cursor),
+    cursor: start,
+    deleted: value.slice(start, cursor),
+  };
+}
+
+/** Remove everything before the cursor (`Ctrl+U`). */
+export function deleteLineBeforeCursor(value: string, cursor: number): ICjkDeletion | undefined {
+  if (cursor <= 0) return undefined;
+  return { value: value.slice(cursor), cursor: 0, deleted: value.slice(0, cursor) };
+}

package/src/flows/cjk-text-input-flow.ts

@@ -0,0 +1,248 @@
+import { moveCursorHorizontally, moveCursorVertically } from './cjk-cursor-motion.js';
+import {
+  deleteCharBeforeCursor,
+  deleteLineBeforeCursor,
+  deleteWordBeforeCursor,
+  type ICjkDeletion,
+} from './cjk-text-deletion.js';
+import type {
+  ICjkTextInputFlowState,
+  TCjkDeletionScope,
+  TCjkTextInputEffect,
+} from './cjk-text-input-types.js';
+
+const PASTE_START = '[200~';
+const PASTE_END = '[201~';
+const LAST_ASCII_CONTROL_CODE = 0x1f;
+const DELETE_CONTROL_CODE = 0x7f;
+
+export { charIndexAtDisplayOffset, displayOffset } from './cjk-cursor-motion.js';
+export type {
+  ICjkTextInputFlowState,
+  TCjkDeletionScope,
+  TCjkTextInputEffect,
+} from './cjk-text-input-types.js';
+
+export interface ICjkTextInputKey {
+  ctrl?: boolean;
+  tab?: boolean;
+  shift?: boolean;
+  upArrow?: boolean;
+  downArrow?: boolean;
+  return?: boolean;
+  leftArrow?: boolean;
+  rightArrow?: boolean;
+  backspace?: boolean;
+  delete?: boolean;
+}
+
+export interface ICjkTextInputFlowOptions {
+  availableWidth?: number;
+  canPaste: boolean;
+  enableVerticalNavigation?: boolean;
+}
+
+interface ICjkTextInputFlowResult {
+  state: ICjkTextInputFlowState;
+  effect: TCjkTextInputEffect;
+}
+
+export function createCjkTextInputFlowState(value: string): ICjkTextInputFlowState {
+  return { value, cursor: value.length, isPasting: false, pasteBuffer: '' };
+}
+
+export function syncCjkTextInputFlowState(
+  state: ICjkTextInputFlowState,
+  value: string,
+  cursorHint: number | null,
+): ICjkTextInputFlowState {
+  if (value === state.value) {
+    return state;
+  }
+  return {
+    ...state,
+    value,
+    cursor: cursorHint != null ? Math.min(cursorHint, value.length) : value.length,
+  };
+}
+
+export function applyCjkTextInput(
+  state: ICjkTextInputFlowState,
+  input: string,
+  key: ICjkTextInputKey,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult {
+  const pasteResult = applyPasteBoundaryInput(state, input, options);
+  if (pasteResult !== undefined) return pasteResult;
+  const controlResult = applyControlInput(state, input, key, options);
+  if (controlResult !== undefined) return controlResult;
+  const cursorResult = applyCursorInput(state, key, options);
+  if (cursorResult !== undefined) return cursorResult;
+  return insertPrintableInput(state, input);
+}
+
+export function applyCjkTextPaste(
+  state: ICjkTextInputFlowState,
+  text: string,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult {
+  const normalizedText = text.replace(/\r\n?/g, '\n');
+  if (normalizedText.length === 0) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (normalizedText.includes('\n') && options.canPaste) {
+    return { state, effect: { type: 'paste', text: normalizedText, cursor: state.cursor } };
+  }
+  return insertPrintableInput(state, normalizedText);
+}
+
+function applyPasteBoundaryInput(
+  state: ICjkTextInputFlowState,
+  input: string,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult | undefined {
+  if (input === PASTE_START || input.startsWith(PASTE_START)) {
+    return startBracketedPaste(state, input);
+  }
+  if (state.isPasting) {
+    return continueBracketedPaste(state, input, options);
+  }
+  return undefined;
+}
+
+function applyControlInput(
+  state: ICjkTextInputFlowState,
+  input: string,
+  key: ICjkTextInputKey,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult | undefined {
+  if ((key.ctrl === true && input === 'c') || key.tab === true) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (key.ctrl === true && (input === 'w' || input === 'u')) {
+    const scope: TCjkDeletionScope = input === 'w' ? 'word' : 'line';
+    const remove = scope === 'word' ? deleteWordBeforeCursor : deleteLineBeforeCursor;
+    return applyDeletion(state, remove(state.value, state.cursor), scope);
+  }
+  if (key.return === true) {
+    return { state, effect: { type: 'submit', value: state.value } };
+  }
+  if (input.length > 1 && (input.includes('\n') || input.includes('\r')) && options.canPaste) {
+    return {
+      state,
+      effect: { type: 'paste', text: input.replace(/\r\n?/g, '\n'), cursor: state.cursor },
+    };
+  }
+  return undefined;
+}
+
+function applyCursorInput(
+  state: ICjkTextInputFlowState,
+  key: ICjkTextInputKey,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult | undefined {
+  if (key.upArrow === true || key.downArrow === true) {
+    if (options.enableVerticalNavigation === false) {
+      return { state, effect: { type: 'none' } };
+    }
+    return moveCursorVertically(
+      state,
+      key.upArrow === true ? 'up' : 'down',
+      options.availableWidth,
+    );
+  }
+  if (key.leftArrow === true) {
+    return moveCursorHorizontally(state, 'left');
+  }
+  if (key.rightArrow === true) {
+    return moveCursorHorizontally(state, 'right');
+  }
+  if (key.backspace === true || key.delete === true) {
+    return applyDeletion(state, deleteCharBeforeCursor(state.value, state.cursor));
+  }
+  return undefined;
+}
+
+export function filterPrintable(input: string | null | undefined): string {
+  if (!input || input.length === 0) return '';
+  let output = '';
+  for (const char of input) {
+    const code = char.charCodeAt(0);
+    if (code > LAST_ASCII_CONTROL_CODE && code !== DELETE_CONTROL_CODE) {
+      output += char;
+    }
+  }
+  return output;
+}
+
+export function insertAtCursor(
+  value: string,
+  cursor: number,
+  input: string,
+): { value: string; cursor: number } {
+  const next = value.slice(0, cursor) + input + value.slice(cursor);
+  return { value: next, cursor: cursor + input.length };
+}
+
+function startBracketedPaste(
+  state: ICjkTextInputFlowState,
+  input: string,
+): ICjkTextInputFlowResult {
+  return {
+    state: { ...state, isPasting: true, pasteBuffer: input.slice(PASTE_START.length) },
+    effect: { type: 'none' },
+  };
+}
+
+function continueBracketedPaste(
+  state: ICjkTextInputFlowState,
+  input: string,
+  options: ICjkTextInputFlowOptions,
+): ICjkTextInputFlowResult {
+  if (input !== PASTE_END && !input.includes(PASTE_END)) {
+    return {
+      state: { ...state, pasteBuffer: state.pasteBuffer + input },
+      effect: { type: 'none' },
+    };
+  }
+  const beforeMarker = input.split(PASTE_END)[0] ?? '';
+  const nextState = { ...state, isPasting: false, pasteBuffer: '' };
+  return applyCjkTextPaste(nextState, state.pasteBuffer + beforeMarker, options);
+}
+
+/**
+ * Apply a deletion result. A word/line delete carries the removed text so the caller can announce
+ * it; a character delete does not — the reader already heard the character go.
+ */
+function applyDeletion(
+  state: ICjkTextInputFlowState,
+  deletion: ICjkDeletion | undefined,
+  scope?: TCjkDeletionScope,
+): ICjkTextInputFlowResult {
+  if (deletion === undefined) {
+    return { state, effect: { type: 'none' } };
+  }
+  return {
+    state: { ...state, value: deletion.value, cursor: deletion.cursor },
+    effect: {
+      type: 'change',
+      value: deletion.value,
+      ...(scope !== undefined ? { deleted: deletion.deleted, deletedScope: scope } : {}),
+    },
+  };
+}
+
+function insertPrintableInput(
+  state: ICjkTextInputFlowState,
+  input: string,
+): ICjkTextInputFlowResult {
+  const printable = filterPrintable(input);
+  if (printable.length === 0) {
+    return { state, effect: { type: 'none' } };
+  }
+  const result = insertAtCursor(state.value, state.cursor, printable);
+  return {
+    state: { ...state, value: result.value, cursor: result.cursor },
+    effect: { type: 'change', value: result.value },
+  };
+}

package/src/flows/cjk-text-input-types.ts

@@ -0,0 +1,24 @@
+/**
+ * Leaf type module for the CJK text-input flow state and effect union.
+ *
+ * Split out of `cjk-text-input-flow.ts` so `cjk-cursor-motion.ts` can depend on these types
+ * without importing back from `cjk-text-input-flow.ts`, which previously created an import cycle
+ * between the two (`cjk-cursor-motion.ts` -> `cjk-text-input-flow.ts` -> `cjk-cursor-motion.ts`).
+ */
+
+export interface ICjkTextInputFlowState {
+  value: string;
+  cursor: number;
+  isPasting: boolean;
+  pasteBuffer: string;
+}
+
+/** CLI-2004: a word/line delete is announced; a single-character backspace is not (it is heard). */
+export type TCjkDeletionScope = 'word' | 'line';
+
+export type TCjkTextInputEffect =
+  | { type: 'none' }
+  | { type: 'change'; value: string; deleted?: string; deletedScope?: TCjkDeletionScope }
+  | { type: 'submit'; value: string }
+  | { type: 'paste'; text: string; cursor: number }
+  | { type: 'render' };

package/src/flows/confirm-prompt-flow.ts

@@ -0,0 +1,90 @@
+import {
+  applySelectionInput,
+  getDirectionalSelectionInputAction,
+  type ISelectionFlowState,
+  type ISelectionInputKey,
+  type TSelectionEffect,
+  type TSelectionInputAction,
+} from './selection-flow.js';
+
+export type TConfirmPromptInputAction = TSelectionInputAction | { type: 'shortcut'; index: number };
+
+export function getConfirmPromptInputAction(
+  input: string,
+  key: ISelectionInputKey,
+  optionCount: number,
+): TConfirmPromptInputAction | undefined {
+  const action = getDirectionalSelectionInputAction({ ...key, escape: false });
+  if (action !== undefined) {
+    return action;
+  }
+  if (optionCount === 2 && input === 'y') {
+    return { type: 'shortcut', index: 0 };
+  }
+  if (optionCount === 2 && input === 'n') {
+    return { type: 'shortcut', index: 1 };
+  }
+  return undefined;
+}
+
+/**
+ * CLI-2004 — the typed yes/no answer.
+ *
+ * A two-option arrow menu is the worst shape for a reader: both rows are announced, and which one is
+ * selected differs only by a cursor glyph and a colour. In screen-reader mode the prompt asks for a
+ * typed answer instead — `y`, `n`, `yes` or `no`, then Enter. Anything else clears the buffer and
+ * resolves nothing, so a mistyped answer cannot be read as consent.
+ */
+export interface ITypedConfirmState {
+  buffer: string;
+  resolved: boolean;
+}
+
+export function createTypedConfirmState(): ITypedConfirmState {
+  return { buffer: '', resolved: false };
+}
+
+const YES_ANSWERS = ['y', 'yes'];
+const NO_ANSWERS = ['n', 'no'];
+
+export function applyTypedConfirmInput(
+  state: ITypedConfirmState,
+  input: string,
+  key: ISelectionInputKey & { backspace?: boolean; delete?: boolean },
+): { state: ITypedConfirmState; effect: TSelectionEffect } {
+  if (state.resolved) return { state, effect: { type: 'none' } };
+  if (key.backspace === true || key.delete === true) {
+    return { state: { ...state, buffer: state.buffer.slice(0, -1) }, effect: { type: 'none' } };
+  }
+  if (key.return === true) {
+    const answer = state.buffer.trim().toLowerCase();
+    if (YES_ANSWERS.includes(answer)) {
+      return { state: { buffer: '', resolved: true }, effect: { type: 'select', index: 0 } };
+    }
+    if (NO_ANSWERS.includes(answer)) {
+      return { state: { buffer: '', resolved: true }, effect: { type: 'select', index: 1 } };
+    }
+    return { state: { ...state, buffer: '' }, effect: { type: 'none' } };
+  }
+  if (/^[a-zA-Z]+$/.test(input)) {
+    return { state: { ...state, buffer: state.buffer + input }, effect: { type: 'none' } };
+  }
+  return { state, effect: { type: 'none' } };
+}
+
+export function applyConfirmPromptInput(
+  state: ISelectionFlowState,
+  action: TConfirmPromptInputAction,
+  optionCount: number,
+): { state: ISelectionFlowState; effect: TSelectionEffect } {
+  if (state.resolved) {
+    return { state, effect: { type: 'none' } };
+  }
+  if (typeof action !== 'string') {
+    return {
+      state: { ...state, selectedIndex: action.index, resolved: true },
+      effect: { type: 'select', index: action.index },
+    };
+  }
+  return applySelectionInput(state, action, { itemCount: optionCount });
+}

package/src/flows/defer-submit.ts

@@ -0,0 +1,67 @@
+/**
+ * CLI-061 — deferred submit for the CJK-IME last-character-drop race.
+ *
+ * IME composition is finalized by the terminal, which writes the final composed character into the pty as its
+ * OWN stdin event that arrives JUST AFTER the confirming `\r`. If we submit synchronously on Enter, the trailing
+ * syllable has not yet been applied to the input state, so it is dropped (`안녕하세요` → `안녕하세`). Deferring the
+ * submit a few milliseconds lets that trailing event land, after which we re-read the LATEST value and submit it.
+ *
+ * This is the same app-layer fix Gemini CLI applied on the same Ink (PR #4987/#7556); no framework change and
+ * no upstream Ink dependency (Ink #759 stays a watch-only item).
+ *
+ * Injectable `schedule`/`clear` (defaulting to the real timer) keep this unit deterministically testable —
+ * there is NO fake timer shipped in `src`; a test injects its own scheduler.
+ */
+
+/**
+ * Defer window before a submit fires. Larger = safer against a slow/remote pty delivering the trailing event
+ * late, but adds this latency to EVERY submit (including plain ASCII). 50ms matches Gemini's default — long
+ * enough for a local IME finalize, short enough to feel instant. This NARROWS the race; on a very slow pty the
+ * trailing event can still land after the window (residual, accepted).
+ */
+export const IME_SUBMIT_DEFER_MS = 50;
+
+type TTimer = ReturnType<typeof setTimeout>;
+
+export interface IDeferSubmitState {
+  timer: TTimer | null;
+  /** Gates a SECOND submit / Enter only — never the input pipeline (the trailing char must still be processed). */
+  isSubmitting: boolean;
+}
+
+export function createDeferSubmitState(): IDeferSubmitState {
+  return { timer: null, isSubmitting: false };
+}
+
+/**
+ * Schedule a deferred submit. At fire time it reads `readLatest()` (the LIVE input value, not a value captured
+ * at Enter time) and submits it. A submit already in flight is ignored (no double-submit) — but note the caller
+ * MUST keep its input pipeline live during the window so `readLatest()` sees the trailing character.
+ */
+export function scheduleDeferredSubmit(
+  state: IDeferSubmitState,
+  readLatest: () => string,
+  submit: (value: string) => void,
+  deferMs: number = IME_SUBMIT_DEFER_MS,
+  schedule: (fn: () => void, ms: number) => TTimer = setTimeout,
+): void {
+  if (state.isSubmitting) return; // second Enter within the window — ignore, do not double-submit
+  state.isSubmitting = true;
+  state.timer = schedule(() => {
+    state.timer = null;
+    state.isSubmitting = false;
+    submit(readLatest());
+  }, deferMs);
+}
+
+/** Cancel a pending deferred submit (call on unmount so no submit fires after teardown and no timer leaks). */
+export function cancelDeferredSubmit(
+  state: IDeferSubmitState,
+  clear: (timer: TTimer) => void = clearTimeout,
+): void {
+  if (state.timer !== null) {
+    clear(state.timer);
+    state.timer = null;
+  }
+  state.isSubmitting = false;
+}

package/src/flows/fork-attach-flow.ts

@@ -0,0 +1,62 @@
+/**
+ * CLI-1994: the TUI half of `attach` — turning the workspace entry the operator picked into either
+ * a session switch or a stated refusal.
+ *
+ * The DECISION is not made here. `resolveExecutionAttach` is the framework's, beside the projection
+ * that decides when the control is offered, so the surface cannot invent a second answer to "may
+ * this be attached to". What this module owns is the surface's part: the refusal reaches the
+ * operator as a message, and the switch goes through the SAME session-switch path the session
+ * picker uses — a new channel from the factory, the previous one stopped first.
+ *
+ * A switch is a VIEW change. Nothing is merged: the parent session's record is not read or written,
+ * and the two records stay separate exactly as `/fork` left them.
+ */
+
+import { resolveExecutionAttach } from '@robota-sdk/agent-framework';
+
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+
+/** The `switch-session` member of the command layer's UI-intent union, narrowed to itself. */
+/**
+ * What an attach did: the session this terminal was pointed at.
+ *
+ * Deliberately NOT a `TCommandUiIntent` member. Attach starts at a keypress in this surface's own
+ * background panel, not at a command, so routing it through the requester-routed intent bus would
+ * add a hop with no second consumer at the end of it — and the intent's `useSideEffects` case had no
+ * emitter, which is a reader with no writer.
+ */
+export interface IForkAttachOutcome {
+  readonly sessionId: string;
+}
+
+export interface IForkAttachDeps {
+  /** Whether the forked record is still in the store this surface would switch onto. */
+  readonly hasSessionRecord: (sessionId: string) => boolean;
+  /** The surface's existing session-switch path — the one the session picker calls. */
+  readonly switchSession: (sessionId: string) => void;
+  /** How a refusal reaches the operator (a system entry in the transcript). */
+  readonly notify: (message: string) => void;
+  /** Optional host-owned command for reopening a completed fork outside the attach view. */
+  readonly formatResumeCommand?: (sessionId: string) => string;
+}
+
+/**
+ * Attach to `entry`'s forked session, or tell the operator why not.
+ *
+ * Returns the UI intent that was emitted, so a caller — and a test — can see the switch as the
+ * command layer's own vocabulary rather than as a side effect. `undefined` means refused, and the
+ * refusal has already been delivered through `notify`.
+ */
+export function attachToForkedSession(
+  entry: IExecutionWorkspaceEntry,
+  deps: IForkAttachDeps,
+): IForkAttachOutcome | undefined {
+  const outcome = resolveExecutionAttach(entry, { hasSessionRecord: deps.hasSessionRecord });
+  if (outcome.type === 'refused') {
+    const resumeCommand = outcome.resumeSessionId && deps.formatResumeCommand?.(outcome.resumeSessionId);
+    deps.notify(resumeCommand ? `${outcome.reason} Open it with: ${resumeCommand}` : outcome.reason);
+    return undefined;
+  }
+  deps.switchSession(outcome.sessionId);
+  return { sessionId: outcome.sessionId };
+}