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

package/src/render.tsx

@@ -23,13 +23,20 @@ import type { ITerminalCapabilityOverrides } from './terminal-capabilities-conte
 import { createFocusReportingWriter } from './terminal-focus-reporting.js';
 import { TerminalHandoffController } from './terminal-handoff-controller.js';
 import { TuiInteractionChannel } from './TuiInteractionChannel.js';
+import { WireTuiChannel } from './wire-tui-channel.js';
 
+import type {
+  IAttachedSessionConnection,
+  TAttachedSessionEnd,
+} from './attached-session-connection.js';
+import type { IAttentionSource } from './attention/attention-tracker.js';
 import type { IKeybindingsSource } from './keybindings/node-keybindings-source.js';
 import type { TScreenReaderChannel } from './screen-reader-announcement.js';
 import type { IThemeRegistry } from './theme/theme-registry.js';
 import type { ITuiAppChannelPort } from './tui-app-channel-port.js';
 import type { ITuiCliAdapter } from './tui-cli-adapter.js';
 import type { ITuiInteractionChannelOptions } from './TuiInteractionChannel.js';
+import type { ITuiClientCommands } from './wire-tui-client-commands.js';
 import type {
   IAIProvider,
   IToolWithEventService,
@@ -52,6 +59,7 @@ import type {
   IPerTurnRecallConfig,
   TWorkspaceProjectAccess,
   EditCheckpointStore,
+  TInteractiveSessionOptions,
   IOrgPolicy,
   IProviderErrorGuidance,
   IProjectSettingsPath,
@@ -104,8 +112,19 @@ export interface IRenderOptions {
    * is what disabled the one check that would have caught the missing declaration.
    */
   orgPolicy?: IOrgPolicy | undefined;
-  /** Explicit authority- and permission-backed edit checkpoint capability. */
-  editCheckpointStore?: EditCheckpointStore;
+  /**
+   * Builds the authority- and permission-backed edit checkpoint store for one session; absent, no
+   * session keeps checkpoints. A factory, not a store: a session switch builds the next channel
+   * while the old session may still be finishing a turn, and a store holds one turn in progress.
+   */
+  createEditCheckpointStore?: () => EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /**
+   * #3189: the run's grant history, handed to every session this TUI builds so a switch replays no
+   * spent token and resets no rate. DECLARED for the reason `orgPolicy` above is.
+   */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
   providerOverride?: string | undefined;
   /**
    * #1844: forwarded to the session so `/provider switch` can construct the provider it switches TO.
@@ -165,6 +184,8 @@ export interface IRenderOptions {
    */
   additionalTools?: IToolWithEventService[];
   defaultTools?: readonly IToolWithEventService[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
   commandModules?: readonly ICommandModule[];
   commandHostAdapters?: ICommandHostAdapters;
   shellExec?: TShellExecFn;
@@ -285,8 +306,11 @@ export function toChannelOptions(
       ? { userSettingsSources: options.userSettingsSources }
       : {}),
     ...(options.orgPolicy !== undefined ? { orgPolicy: options.orgPolicy } : {}),
-    ...(options.editCheckpointStore !== undefined
-      ? { editCheckpointStore: options.editCheckpointStore }
+    ...(options.externalEventVerifierFactory !== undefined
+      ? { externalEventVerifierFactory: options.externalEventVerifierFactory }
+      : {}),
+    ...(options.externalEventGrantHistory !== undefined
+      ? { externalEventGrantHistory: options.externalEventGrantHistory }
       : {}),
     ...(options.providerDefinitions ? { providerDefinitions: options.providerDefinitions } : {}),
     // CLI-076: the display model id doubles as the session's model override so `--model` actually reaches
@@ -327,6 +351,7 @@ export function toChannelOptions(
       : {}),
     ...(options.additionalTools !== undefined ? { additionalTools: options.additionalTools } : {}),
     ...(options.defaultTools !== undefined ? { defaultTools: options.defaultTools } : {}),
+    ...(options.sandboxClient !== undefined ? { sandboxClient: options.sandboxClient } : {}),
     commandModules: options.commandModules,
     commandHostAdapters: options.commandHostAdapters,
     shellExec: options.shellExec,
@@ -380,21 +405,195 @@ export async function renderApp(options: IRenderOptions): Promise<void> {
   // is the product assembly's boundary (agent-cli installs the guards via onChannelReady).
   try {
     await options.keybindingsSource?.start();
-    await renderStartedApp(options);
+    await renderStartedApp(options, (services) => ({
+      createChannel: createInProcessChannelFactory(options, services),
+    }));
+  } finally {
+    options.keybindingsSource?.dispose();
+  }
+}
+
+/**
+ * What the full TUI needs to attach to a session a host runs (a daemon) instead of building one.
+ * Only presentation options: everything else belongs to the host's session.
+ */
+export interface IRenderAttachedAppOptions extends Pick<
+  IRenderOptions,
+  | 'cwd'
+  | 'productDisplayName'
+  | 'version'
+  | 'cliAdapter'
+  | 'screenReader'
+  | 'screenReaderChannel'
+  | 'screenReaderHint'
+  | 'screenReaderPacing'
+  | 'terminalCapabilities'
+  | 'keybindingsSource'
+  | 'themeRegistry'
+  | 'reducedMotion'
+  | 'reducedMotionOverride'
+  | 'focusReporting'
+  | 'promptHistorySource'
+  | 'promptHistoryProject'
+> {
+  /** The session protocol connection; closing it belongs to the caller. */
+  readonly connection: IAttachedSessionConnection;
+  /** Shown as the session's label until the session reports its own name. */
+  readonly sessionLabel: string;
+  /** This terminal's driver id, from the attach handshake. */
+  readonly driverId: string;
+  /** Commands this terminal runs itself (`/shell`, `/theme`, ...); the host never sees them. */
+  readonly clientCommands?: ITuiClientCommands;
+  /**
+   * How this terminal is on the session: `'drive'` (the default) sends prompts and answers questions;
+   * `'observe'` only watches, and the host refuses anything else from it.
+   */
+  readonly mode?: 'drive' | 'observe';
+  /** Print the screen-reader line; false when this process already printed it. Default true. */
+  readonly announce?: boolean;
+}
+
+/**
+ * Render the full TUI on a session the terminal is attached to over the session protocol. Leaving
+ * only detaches: the session keeps running. Resolves `'user'` when the user leaves (`/exit`,
+ * Ctrl-C) and `'closed'` when the connection closed.
+ */
+export async function renderAttachedApp(
+  options: IRenderAttachedAppOptions,
+): Promise<TAttachedSessionEnd> {
+  let end: TAttachedSessionEnd = 'user';
+  let endApp: () => void = () => undefined;
+  const ended = new Promise<void>((resolve) => {
+    endApp = resolve;
+  });
+  try {
+    await options.keybindingsSource?.start();
+    await renderStartedApp(options, (services) => {
+      let channel: WireTuiChannel | undefined;
+      return {
+        // One channel for the App's life: a session switch is the host's, and the channel follows it.
+        createChannel: () =>
+          (channel ??= new WireTuiChannel({
+            connection: options.connection,
+            driverId: options.driverId,
+            sessionName: options.sessionLabel,
+            role: options.mode ?? 'drive',
+            terminalHandoff: services.terminalHandoff,
+            attention: services.attention,
+            ...(options.clientCommands !== undefined
+              ? { clientCommands: options.clientCommands, cwd: options.cwd }
+              : { clientCommands: undefined }),
+            onEnd: (reason) => {
+              end = reason;
+              endApp();
+            },
+          })),
+        requestSessionSwitch: async (sessionId) => channel?.requestSessionSwitch(sessionId),
+        ended,
+      };
+    });
   } finally {
     options.keybindingsSource?.dispose();
   }
+  return end;
+}
+
+/** Presentation options the App shell reads, whichever kind of channel it renders. */
+type TAppShellOptions = Pick<
+  IRenderOptions,
+  | 'cwd'
+  | 'productDisplayName'
+  | 'modelCommandToolPrefix'
+  | 'providerOverride'
+  | 'providerType'
+  | 'modelId'
+  | 'permissionMode'
+  | 'version'
+  | 'sessionStore'
+  | 'resumeSessionId'
+  | 'showSessionPickerOnStart'
+  | 'initialInput'
+  | 'initialInputOrigin'
+  | 'startupUpdateNotice'
+  | 'transportRegistry'
+  | 'commandHostAdapters'
+  | 'cliAdapter'
+  | 'promptHistorySource'
+  | 'promptHistoryProject'
+  | 'themeRegistry'
+  | 'reducedMotion'
+  | 'reducedMotionOverride'
+  | 'screenReader'
+  | 'screenReaderPacing'
+  | 'terminalCapabilities'
+  | 'screenReaderChannel'
+  | 'screenReaderHint'
+  | 'keybindingsSource'
+  | 'focusReporting'
+> & {
+  /** Print the screen-reader line. Default true; false when this process already printed it. */
+  readonly announce?: boolean;
+};
+
+/** Terminal-wide services a channel is built with; they outlive every channel. */
+export interface IChannelServices {
+  readonly terminalHandoff: TerminalHandoffController;
+  readonly attention: IAttentionSource;
+}
+
+/** Where the App's channels come from, and how a session switch and an app end are decided. */
+interface IAppChannelComposition {
+  readonly createChannel: (resumeSessionId?: string) => ITuiAppChannelPort;
+  /** Present when the host switches sessions and the channel follows it. */
+  readonly requestSessionSwitch?: (sessionId: string) => Promise<void>;
+  /** Settles when the app ends without the user closing it (the connection closed). */
+  readonly ended?: Promise<void>;
+}
+
+/**
+ * The in-process factory: every channel builds its own session, and its own checkpoint store, from
+ * the render options. A resumed session's store restores its active branch from the persisted pointer.
+ */
+export function createInProcessChannelFactory(
+  options: IRenderOptions,
+  services: IChannelServices,
+): (resumeSessionId?: string) => ITuiAppChannelPort {
+  // Issue #3081: the move is announced by the FIRST session only — a later switch to another
+  // session (a `/fork` attach) did not move anywhere.
+  let pendingWorkspaceMovedFrom = options.workspaceMovedFrom;
+  return (resumeSessionId) => {
+    const workspaceMovedFrom = pendingWorkspaceMovedFrom;
+    pendingWorkspaceMovedFrom = undefined;
+    const channel = new TuiInteractionChannel({
+      ...toChannelOptions(options, resumeSessionId),
+      ...(options.createEditCheckpointStore !== undefined
+        ? { editCheckpointStore: options.createEditCheckpointStore() }
+        : {}),
+      ...(workspaceMovedFrom !== undefined ? { workspaceMovedFrom } : {}),
+      terminalHandoff: services.terminalHandoff,
+      attention: services.attention,
+    });
+    // Expose each live channel (incl. session-switch re-creations) to the embedding product,
+    // e.g. for process-level error routing (ERR-001 G1).
+    options.onChannelReady?.(channel);
+    return channel;
+  };
 }
 
-async function renderStartedApp(options: IRenderOptions): Promise<void> {
+async function renderStartedApp(
+  options: TAppShellOptions,
+  compose: (services: IChannelServices) => IAppChannelComposition,
+): Promise<void> {
   // CLI-2004: one resolved boolean drives Ink's own screen-reader support AND the React context
   // every component reads. Both are set here so they can never disagree.
   const screenReader = options.screenReader === true;
-  writeScreenReaderAnnouncement({
-    enabled: screenReader,
-    channel: options.screenReaderChannel,
-    hint: options.screenReaderHint,
-  });
+  if (options.announce !== false) {
+    writeScreenReaderAnnouncement({
+      enabled: screenReader,
+      channel: options.screenReaderChannel,
+      hint: options.screenReaderHint,
+    });
+  }
   const pacing = resolvePacing({ enabled: screenReader, overrides: options.screenReaderPacing });
   // SCREEN-2670: the pre-write park. Constructed only when the mode is on AND the interval is
   // non-zero, so with the mode off `stdout` is not passed at all and Ink defaults to
@@ -436,24 +635,11 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
 
   // Concrete framework creation has one composition boundary. React receives only the bounded port;
   // App owns which narrowed channel is active, while each channel owns its own lifecycle.
+  const composition = compose({ terminalHandoff: handoffController, attention });
   let activeChannel: ITuiAppChannelPort | undefined;
-  // Issue #3081: the move is announced by the FIRST session only — a later switch to another
-  // session (a `/fork` attach) did not move anywhere.
-  let pendingWorkspaceMovedFrom = options.workspaceMovedFrom;
   const createChannel = (resumeSessionId?: string): ITuiAppChannelPort => {
-    const workspaceMovedFrom = pendingWorkspaceMovedFrom;
-    pendingWorkspaceMovedFrom = undefined;
-    const channel = new TuiInteractionChannel({
-      ...toChannelOptions(options, resumeSessionId),
-      ...(workspaceMovedFrom !== undefined ? { workspaceMovedFrom } : {}),
-      terminalHandoff: handoffController,
-      attention,
-    });
-    // Expose each live channel (incl. session-switch re-creations) to the embedding product,
-    // e.g. for process-level error routing (ERR-001 G1).
-    options.onChannelReady?.(channel);
-    activeChannel = channel;
-    return channel;
+    activeChannel = composition.createChannel(resumeSessionId);
+    return activeChannel;
   };
 
   // The startup quiet period sits between the confirmation line and the first frame, so a reader
@@ -486,6 +672,9 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
             <App
               cwd={options.cwd}
               createChannel={createChannel}
+              {...(composition.requestSessionSwitch !== undefined
+                ? { requestSessionSwitch: composition.requestSessionSwitch }
+                : {})}
               providerOverride={options.providerOverride}
               providerType={options.providerType}
               modelId={options.modelId}
@@ -526,6 +715,8 @@ async function renderStartedApp(options: IRenderOptions): Promise<void> {
   );
   // The controller needs the Ink instance to clear the frame before a handoff.
   handoffController.setInkInstance(instance);
+  // Unmounting resolves `waitUntilExit`, so an app the host ended leaves the way a user exit does.
+  void composition.ended?.then(() => instance.unmount());
   try {
     await waitForRenderAndStop(
       () => instance.waitUntilExit(),

package/src/short-session-id.ts

@@ -0,0 +1,9 @@
+/** Every stored session id starts with this, so it tells no two sessions apart. */
+const SESSION_ID_PREFIX = 'session_';
+const SHORT_SESSION_ID_LENGTH = 8;
+
+/** A session id short enough for a picker row or a status bar: the start of the part that differs. */
+export function shortSessionId(id: string): string {
+  const distinct = id.startsWith(SESSION_ID_PREFIX) ? id.slice(SESSION_ID_PREFIX.length) : id;
+  return distinct === '' ? id : distinct.slice(0, SHORT_SESSION_ID_LENGTH);
+}

package/src/slash-command-input.ts

@@ -0,0 +1,11 @@
+/** A typed `/name args` line, split the way every TUI channel dispatches it. */
+export interface ISlashCommandInput {
+  /** Lower-cased, without the slash. */
+  readonly name: string;
+  readonly args: string;
+}
+
+export function parseSlashCommandInput(input: string): ISlashCommandInput {
+  const parts = input.slice(1).split(/\s+/);
+  return { name: parts[0]?.toLowerCase() ?? '', args: parts.slice(1).join(' ') };
+}

package/src/tui-app-channel-port.ts

@@ -14,7 +14,11 @@ import type {
   IExecutionDetailPage,
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
-import type { IInteractiveSessionEvents, IToolState } from '@robota-sdk/agent-interface-session';
+import type {
+  IInteractiveSessionEvents,
+  ISessionListingEntry,
+  IToolState,
+} from '@robota-sdk/agent-interface-session';
 
 export interface ITuiCommandQueryPort {
   getCommands(filter?: string): ICommand[];
@@ -33,6 +37,8 @@ export interface ITuiRuntimeStatusSnapshot {
   sessionId: string;
   activePresetId?: string;
   effort?: TModelEffortSelection;
+  /** The model the session reports, when its host says; absent ⇒ the one this terminal was started with. */
+  modelId?: string;
 }
 
 export interface ITuiChannelSnapshot {
@@ -52,6 +58,28 @@ export interface ITuiChannelSnapshot {
   permissionRequest: IPendingPermissionRequest | null;
   pendingUserAction: IActionRequest | null;
   contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  /**
+   * The sessions the session picker offers, when the host keeps them (a terminal attached to a
+   * daemon). Absent ⇒ the picker lists this terminal's own session store. A host that keeps sessions
+   * live says which rows run now and how many clients are on each; the picker shows both.
+   */
+  hostSessions?: readonly ISessionListingEntry[];
+  /**
+   * Changes when the transcript starts over for another session while the App keeps this channel.
+   * The terminal prints the transcript once and counts what it printed, so a new transcript is
+   * printed from its start. Absent ⇒ the transcript never starts over under this channel.
+   */
+  transcriptGeneration?: number;
+  /**
+   * True while this terminal only observes the session: it sends nothing that changes it, and the
+   * App offers no key that would. Absent ⇒ the terminal drives the session.
+   */
+  readOnly?: boolean;
+  /**
+   * True when this terminal is attached to a session a host runs: leaving only detaches it, and
+   * Ctrl-] leaves too. Absent ⇒ the terminal runs its own session, where Ctrl-] means nothing.
+   */
+  attached?: boolean;
 }
 
 /**

package/src/tui-channel-options.ts

@@ -20,6 +20,7 @@ import type {
   ICreateSessionOptions,
   ILivePromptTracePort,
   EditCheckpointStore,
+  TInteractiveSessionOptions,
   IMemoryStore,
   IPromptHistoryOptions,
   IPerTurnRecallConfig,
@@ -79,8 +80,15 @@ export interface ITuiInteractionChannelOptions {
   contributionSources?: ICreateSessionOptions['contributionSources'];
   skillRoots?: ICreateSessionOptions['skillRoots'];
   userSettingsSources?: readonly INodeHostSettingsSource[];
-  /** Explicit authority- and permission-backed edit checkpoint capability. */
+  /**
+   * Explicit authority- and permission-backed edit checkpoint capability for this channel's one
+   * session. Never shared with another channel's session: a store holds one turn in progress.
+   */
   editCheckpointStore?: EditCheckpointStore;
+  /** The host's way to build each external-event grant's verifier; absent, no grant opens. */
+  externalEventVerifierFactory?: TInteractiveSessionOptions['externalEventVerifierFactory'];
+  /** The run's grant history, shared by every session this TUI binds (#3189). */
+  externalEventGrantHistory?: TInteractiveSessionOptions['externalEventGrantHistory'];
   /**
    * CLI-076: the resolved model id (the same value the status line displays). Forwarded to the session so an
    * explicit `--model` override reaches the provider chat call instead of being silently replaced by the
@@ -106,7 +114,6 @@ export interface ITuiInteractionChannelOptions {
   /** Issue #3081: this channel's session is the target of a `/cd` from this directory. */
   workspaceMovedFrom?: string;
   sessionName?: string;
-  onAutoNamed?: (name: string) => void;
   backgroundTaskRunners?: IBackgroundTaskRunner[];
   /** MCP-004: forwarded to `ICreateSessionOptions.toolCallHandoff`. */
   toolCallHandoff?: IToolCallHandoffPolicy;
@@ -122,6 +129,8 @@ export interface ITuiInteractionChannelOptions {
    */
   additionalTools?: IToolWithEventService[];
   defaultTools?: readonly IToolWithEventService[];
+  /** The sandbox the shell tools run under, so the session can let a confined command skip the prompt. */
+  sandboxClient?: ICreateSessionOptions['sandboxClient'];
   commandModules?: readonly ICommandModule[];
   commandHostAdapters?: ICommandHostAdapters;
   shellExec?: TShellExecFn;

package/src/tui-session-event-projector.ts

@@ -19,7 +19,6 @@ import type {
 export interface ITuiSessionEventProjectorOptions {
   session: InteractiveSession;
   manager: TuiStateManager;
-  onUserMessage: (content: string) => void;
   requestPermission: (
     toolName: string,
     toolArgs: TToolArgs,
@@ -45,7 +44,6 @@ export class TuiSessionEventProjector {
     const { session, manager, attention } = this.options;
 
     const onUserMessage = (content: string): void => {
-      this.options.onUserMessage(content);
       manager.addUserEcho(attributedUserEcho(content, session));
     };
     const syncHistory = (): void => manager.syncHistory(session.getFullHistory());

package/src/tui-session-events.ts

@@ -35,6 +35,12 @@ export const TUI_SESSION_EVENT_CLASSIFICATION = {
   ui_intent: 'react-side-effect',
   session_renamed: 'react-side-effect',
   history_cleared: 'channel',
+  // #3189: a host's session slot emits it on a switch; the TUI switches by remounting its own
+  // channel onto the next session, so it never follows a slot.
+  session_switched: 'non-surface',
+  // A host forwards it to attached clients as `session_status`; this channel owns its session and
+  // reads the status from it on each render.
+  status_changed: 'non-surface',
 } as const satisfies Record<TInteractiveEventName, TTuiSessionEventClassification>;
 
 export interface ITuiSessionEventNotice {

package/src/tui-session-options.ts

@@ -55,6 +55,12 @@ export function buildTuiSessionOptions(
     ...(opts.editCheckpointStore !== undefined
       ? { editCheckpointStore: opts.editCheckpointStore }
       : {}),
+    ...(opts.externalEventVerifierFactory !== undefined
+      ? { externalEventVerifierFactory: opts.externalEventVerifierFactory }
+      : {}),
+    ...(opts.externalEventGrantHistory !== undefined
+      ? { externalEventGrantHistory: opts.externalEventGrantHistory }
+      : {}),
     // CLI-076: forward the resolved model so `--model` takes effect rather than falling through to the
     // session's config/default model.
     ...(opts.model !== undefined ? { model: opts.model } : {}),
@@ -80,6 +86,8 @@ export function buildTuiSessionOptions(
       ? { workspaceMovedFrom: opts.workspaceMovedFrom }
       : {}),
     sessionName: opts.sessionName,
+    // The session names itself after its first real turn, unless it already has a name.
+    autoName: true,
     backgroundTaskRunners: opts.backgroundTaskRunners,
     ...(opts.toolCallHandoff !== undefined ? { toolCallHandoff: opts.toolCallHandoff } : {}),
     subagentRunnerFactory: opts.subagentRunnerFactory,
@@ -90,6 +98,7 @@ export function buildTuiSessionOptions(
     ...(opts.pluginDirectories !== undefined ? { pluginDirectories: opts.pluginDirectories } : {}),
     ...(opts.additionalTools !== undefined ? { additionalTools: opts.additionalTools } : {}),
     ...(opts.defaultTools !== undefined ? { defaultTools: opts.defaultTools } : {}),
+    ...(opts.sandboxClient !== undefined ? { sandboxClient: opts.sandboxClient } : {}),
     commandModules: opts.commandModules,
     commandHostAdapters: opts.commandHostAdapters,
     shellExec: opts.shellExec,

package/src/tui-state-manager.ts

@@ -163,7 +163,7 @@ export class TuiStateManager {
     this.notify();
   };
 
-  onComplete = (result: IExecutionResult): void => {
+  onComplete = (result: Pick<IExecutionResult, 'contextState'>): void => {
     this.clearStallTimer();
     this.debouncedStreamNotify.flush();
     this.streamBuf = '';
@@ -215,6 +215,21 @@ export class TuiStateManager {
    */
   syncHistory(entries: IHistoryEntry[]): void {
     if (entries.length === 0) return;
+    this.history = this.withLocalNotices(entries);
+    this.notify();
+  }
+
+  /**
+   * A host's history as a terminal attached to it last read it, then the echoes of prompts the host
+   * has not recorded yet. Unlike `syncHistory`, an empty history is an answer: the host's session
+   * has no entries.
+   */
+  syncHostHistory(entries: readonly IHistoryEntry[], echoes: readonly IHistoryEntry[]): void {
+    this.history = [...this.withLocalNotices(entries), ...echoes];
+    this.notify();
+  }
+
+  private withLocalNotices(entries: readonly IHistoryEntry[]): IHistoryEntry[] {
     // `<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[] = [];
@@ -225,8 +240,7 @@ export class TuiStateManager {
       merged.push(notice.entry);
     }
     while (next < entries.length) merged.push(entries[next++]!);
-    this.history = merged;
-    this.notify();
+    return merged;
   }
 
   /** Add a notice this terminal owns; it survives the next session-history sync in place. */

package/src/waiting-loop-stop-notice.ts

@@ -0,0 +1,23 @@
+/**
+ * What Esc on an idle prompt says after asking the session to stop its waiting self-paced loop.
+ * The session decides which loop, if any, stops; both channels show its answer in the same words.
+ */
+
+import type { TWaitingLoopStopOutcome } from '@robota-sdk/agent-interface-session';
+
+/** The reason the session records for a loop Esc stopped. */
+export const WAITING_LOOP_STOP_REASON = 'Loop stopped by Esc';
+
+/** The notice for an outcome; none when no loop was waiting. */
+export function waitingLoopStopNotice(outcome: TWaitingLoopStopOutcome): string | undefined {
+  switch (outcome.kind) {
+    case 'none':
+      return undefined;
+    case 'several':
+      return outcome.message;
+    case 'stopped':
+      return `Loop ${outcome.loopId} stopped by Esc.`;
+    case 'failed':
+      return outcome.message;
+  }
+}