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

package/src/tui-interaction-queues.ts

@@ -0,0 +1,163 @@
+import type { IPendingPermissionRequest } from './types.js';
+import type { IActionRequest, TActionResponse, TToolArgs } from '@robota-sdk/agent-core';
+import type { TPermissionResultValue } from '@robota-sdk/agent-interface-session';
+
+interface IUserActionQueueEntry {
+  presentedRequest: IActionRequest;
+  resolve: (response: TActionResponse) => void;
+  id?: string;
+}
+
+interface IPermissionQueueEntry {
+  toolName: string;
+  toolArgs: TToolArgs;
+  canPersistProjectPermission?: boolean;
+  requestedByPeer?: string;
+  resolve: (result: TPermissionResultValue) => void;
+  id?: string;
+}
+
+/** Serializes action prompts and guarantees every pending promise is settled during teardown. */
+export class TuiUserActionQueue {
+  private entries: IUserActionQueueEntry[] = [];
+  private processing = false;
+
+  constructor(private readonly onChange: () => void) {}
+
+  get current(): IActionRequest | null {
+    return this.processing ? (this.entries[0]?.presentedRequest ?? null) : null;
+  }
+
+  enqueue(request: IActionRequest, id?: string): Promise<TActionResponse> {
+    return new Promise<TActionResponse>((resolve) => {
+      this.entries.push({
+        presentedRequest: { ...request },
+        resolve,
+        ...(id !== undefined ? { id } : {}),
+      });
+      this.processNext();
+    });
+  }
+
+  resolveCurrent(expectedRequest: IActionRequest, response: TActionResponse): void {
+    if (this.entries[0]?.presentedRequest !== expectedRequest) return;
+    const pending = this.entries.shift();
+    if (!pending) return;
+    this.processing = false;
+    this.onChange();
+    pending.resolve(response);
+    this.processNext();
+  }
+
+  dismissById(id: string): boolean {
+    const dismissed = this.entries.filter((entry) => entry.id === id);
+    if (dismissed.length === 0) return false;
+    this.entries = this.entries.filter((entry) => entry.id !== id);
+    this.processing = false;
+    for (const entry of dismissed) entry.resolve({ type: 'cancelled' });
+    this.processNext();
+    return true;
+  }
+
+  cancelAll(): void {
+    const queued = this.entries;
+    this.entries = [];
+    this.processing = false;
+    for (const pending of queued) pending.resolve({ type: 'cancelled' });
+    this.onChange();
+  }
+
+  private processNext(): void {
+    if (this.processing) return;
+    if (!this.entries[0]) {
+      this.onChange();
+      return;
+    }
+    this.processing = true;
+    this.onChange();
+  }
+}
+
+/** Serializes permission prompts and denies every pending request during teardown. */
+export class TuiPermissionQueue {
+  private entries: IPermissionQueueEntry[] = [];
+  private processing = false;
+  private currentRequest: IPendingPermissionRequest | null = null;
+
+  constructor(private readonly onChange: () => void) {}
+
+  get current(): IPendingPermissionRequest | null {
+    return this.currentRequest;
+  }
+
+  enqueue(
+    toolName: string,
+    toolArgs: TToolArgs,
+    id?: string,
+    canPersistProjectPermission?: boolean,
+    requestedByPeer?: string,
+  ): Promise<TPermissionResultValue> {
+    return new Promise<TPermissionResultValue>((resolve) => {
+      this.entries.push({
+        toolName,
+        toolArgs,
+        resolve,
+        ...(id !== undefined ? { id } : {}),
+        ...(canPersistProjectPermission !== undefined ? { canPersistProjectPermission } : {}),
+        ...(requestedByPeer !== undefined ? { requestedByPeer } : {}),
+      });
+      this.processNext();
+    });
+  }
+
+  dismissById(id: string): boolean {
+    const dismissed = this.entries.filter((entry) => entry.id === id);
+    if (dismissed.length === 0) return false;
+    const dismissedCurrent = this.entries[0]?.id === id;
+    this.entries = this.entries.filter((entry) => entry.id !== id);
+    for (const entry of dismissed) entry.resolve(false);
+    if (dismissedCurrent) {
+      this.processing = false;
+      this.currentRequest = null;
+      this.processNext();
+    }
+    return true;
+  }
+
+  cancelAll(): void {
+    const queued = this.entries;
+    this.entries = [];
+    this.processing = false;
+    this.currentRequest = null;
+    for (const pending of queued) pending.resolve(false);
+    this.onChange();
+  }
+
+  private processNext(): void {
+    if (this.processing) return;
+    const next = this.entries[0];
+    if (!next) {
+      this.currentRequest = null;
+      this.onChange();
+      return;
+    }
+    this.processing = true;
+    this.currentRequest = {
+      toolName: next.toolName,
+      toolArgs: next.toolArgs,
+      ...(next.canPersistProjectPermission !== undefined
+        ? { canPersistProjectPermission: next.canPersistProjectPermission }
+        : {}),
+      ...(next.requestedByPeer !== undefined ? { requestedByPeer: next.requestedByPeer } : {}),
+      resolve: (result) => {
+        if (this.entries[0] !== next) return;
+        this.entries.shift();
+        this.processing = false;
+        this.currentRequest = null;
+        next.resolve(result);
+        setTimeout(() => this.processNext(), 0);
+      },
+    };
+    this.onChange();
+  }
+}

package/src/tui-session-binding.ts

@@ -0,0 +1,52 @@
+import type { TuiStateManager } from './tui-state-manager.js';
+import type {
+  IInteractiveSession,
+  IInteractiveSessionEvents,
+  TInteractiveEventName,
+} from '@robota-sdk/agent-interface-session';
+
+export interface ITuiSessionEventBinding {
+  event: TInteractiveEventName;
+  handler: (...args: never[]) => void;
+}
+
+export interface ITuiSessionBinder {
+  <E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+}
+
+export function bindTuiSessionNoticeEvents(
+  bind: ITuiSessionBinder,
+  manager: TuiStateManager,
+): void {
+  bind('plan_event', (payload) => manager.addSessionEventNotice({ event: 'plan_event', payload }));
+  bind('context_file_refreshed', (payload) =>
+    manager.addSessionEventNotice({ event: 'context_file_refreshed', payload }),
+  );
+  bind('branch_event', (payload) =>
+    manager.addSessionEventNotice({ event: 'branch_event', payload }),
+  );
+}
+
+/** Isolate a TUI-owned projection failure from the session operation that already committed. */
+export function bindTuiSessionEvent<E extends TInteractiveEventName>(
+  session: Pick<IInteractiveSession, 'on'>,
+  event: E,
+  handler: IInteractiveSessionEvents[E],
+  onDeliveryError: (error: Error, event: E) => void,
+  bindings: ITuiSessionEventBinding[],
+): void {
+  const ownedHandler = ((...args: never[]): void => {
+    try {
+      (handler as (...values: never[]) => void)(...args);
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      try {
+        onDeliveryError(normalized, event);
+      } catch {
+        // Diagnostics cannot make a committed session operation fail.
+      }
+    }
+  }) as IInteractiveSessionEvents[E];
+  session.on(event, ownedHandler);
+  bindings.push({ event, handler: ownedHandler as (...args: never[]) => void });
+}

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

@@ -0,0 +1,140 @@
+import { printablePeerDriver } from '@robota-sdk/agent-core';
+
+import { attributedUserEcho } from './attributed-user-echo.js';
+import { bindTuiSessionEvent, bindTuiSessionNoticeEvents } from './tui-session-binding.js';
+
+import type { AttentionCoordinator } from './attention/attention-coordinator.js';
+import type { ITuiSessionEventBinding } from './tui-session-binding.js';
+import type { TuiStateManager } from './tui-state-manager.js';
+import type { IActionRequest, TActionResponse, TToolArgs } from '@robota-sdk/agent-core';
+import type { InteractiveSession } from '@robota-sdk/agent-framework';
+import type { IExecutionWorkspaceEvent } from '@robota-sdk/agent-interface-execution';
+import type {
+  IExecutionResult,
+  IInteractiveSessionEvents,
+  TInteractiveEventName,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-interface-session';
+
+export interface ITuiSessionEventProjectorOptions {
+  session: InteractiveSession;
+  manager: TuiStateManager;
+  onUserMessage: (content: string) => void;
+  requestPermission: (
+    toolName: string,
+    toolArgs: TToolArgs,
+    id: string,
+    canPersistProjectPermission?: boolean,
+    requestedByPeer?: string,
+  ) => Promise<TPermissionResultValue>;
+  askUser: (request: IActionRequest, id: string) => Promise<TActionResponse>;
+  dismissPrompt: (id: string) => void;
+  onDeliveryError?: (error: Error, event: TInteractiveEventName) => void;
+  /** SCREEN-1992: fed the events the interval recap counts; absent ⇒ nothing is counted. */
+  attention?: AttentionCoordinator;
+}
+
+/** Projects runtime session events into TUI state and owns the complete listener lifecycle. */
+export class TuiSessionEventProjector {
+  private readonly bindings: ITuiSessionEventBinding[] = [];
+
+  constructor(private readonly options: ITuiSessionEventProjectorOptions) {}
+
+  wire(): void {
+    if (this.bindings.length > 0) return;
+    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());
+    const onComplete = (result: IExecutionResult): void => {
+      manager.onComplete(result);
+      attention?.onComplete();
+      syncHistory();
+    };
+    const onError = (error: Error): void => {
+      manager.onError(error);
+      attention?.onError();
+      syncHistory();
+    };
+    const onExecutionWorkspaceEvent = (event: IExecutionWorkspaceEvent): void => {
+      manager.syncExecutionWorkspaceSnapshot(event.snapshot);
+      attention?.onWorkspaceSnapshot(event.snapshot);
+    };
+
+    this.bind('user_message', onUserMessage);
+    this.bind('text_delta', manager.onTextDelta);
+    this.bind('tool_start', manager.onToolStart);
+    this.bind('tool_end', manager.onToolEnd);
+    this.bind('thinking', manager.onThinking);
+    this.bind('complete', onComplete);
+    this.bind('interrupted', manager.onInterrupted);
+    this.bind('error', onError);
+    this.bind('context_update', manager.onContextUpdate);
+    this.bind('compact', syncHistory);
+    this.bind('skill_activation', syncHistory);
+    this.bind('memory_event', syncHistory);
+    this.bind('execution_workspace_event', onExecutionWorkspaceEvent);
+    this.bind('history_cleared', () => manager.clearHistory());
+    // SCREEN-1992: subscribed regardless, so the channel's subscribed set equals the classification.
+    this.bind('turn_source', (source) => attention?.onTurnSource(source));
+    bindTuiSessionNoticeEvents(this.bind.bind(this), manager);
+
+    const onPermissionRequest: IInteractiveSessionEvents['permission_request'] = ({
+      id,
+      toolName,
+      toolArgs,
+      canPersistProjectPermission,
+      requesterDriverId,
+    }) => {
+      attention?.onNeedsInput();
+      // A peer turn's ask names the peer, printed only as a plain identifier.
+      const requestedByPeer = requesterDriverId?.startsWith('peer:')
+        ? printablePeerDriver(requesterDriverId)
+        : undefined;
+      void this.options
+        .requestPermission(toolName, toolArgs, id, canPersistProjectPermission, requestedByPeer)
+        .then((result) => session.resolvePermission(id, result))
+        .catch(() => session.resolvePermission(id, false));
+    };
+    const onAskRequest: IInteractiveSessionEvents['ask_request'] = ({ id, request }) => {
+      attention?.onNeedsInput();
+      void this.options
+        .askUser(request, id)
+        .then((response) => session.resolveAsk(id, response))
+        .catch(() => session.resolveAsk(id, { type: 'cancelled' }));
+    };
+    this.bind('permission_request', onPermissionRequest);
+    this.bind('ask_request', onAskRequest);
+    this.bind('prompt_resolved', ({ id }) => this.options.dismissPrompt(id));
+    attention?.wire();
+  }
+
+  unwire(): void {
+    const { session } = this.options;
+    this.options.attention?.unwire();
+    for (const { event, handler } of this.bindings) {
+      session.off(event, handler as IInteractiveSessionEvents[typeof event]);
+    }
+    this.bindings.length = 0;
+  }
+
+  private bind<E extends TInteractiveEventName>(
+    event: E,
+    handler: IInteractiveSessionEvents[E],
+  ): void {
+    bindTuiSessionEvent(
+      this.options.session,
+      event,
+      handler,
+      (error) => {
+        const report = this.options.onDeliveryError;
+        if (report) report(error, event);
+        else this.options.manager.addSessionEventDeliveryError(error, event);
+      },
+      this.bindings,
+    );
+  }
+}

package/src/tui-session-events.ts

@@ -0,0 +1,82 @@
+import type {
+  IBranchEvent,
+  IContextFileRefreshedEvent,
+  IPlanApprovalEvent,
+  TInteractiveEventName,
+} from '@robota-sdk/agent-interface-session';
+
+export type TTuiSessionEventClassification = 'channel' | 'react-side-effect' | 'non-surface';
+
+/** Exhaustive TUI-owner policy over the shared session-event vocabulary. */
+export const TUI_SESSION_EVENT_CLASSIFICATION = {
+  text_delta: 'channel',
+  tool_start: 'channel',
+  tool_end: 'channel',
+  thinking: 'channel',
+  complete: 'channel',
+  error: 'channel',
+  context_update: 'channel',
+  compact: 'channel',
+  interrupted: 'channel',
+  skill_activation: 'channel',
+  background_task_event: 'non-surface',
+  background_job_group_event: 'non-surface',
+  execution_workspace_event: 'channel',
+  user_message: 'channel',
+  turn_source: 'channel',
+  context_file_refreshed: 'channel',
+  memory_event: 'channel',
+  goal_event: 'non-surface',
+  plan_event: 'channel',
+  branch_event: 'channel',
+  permission_request: 'channel',
+  ask_request: 'channel',
+  prompt_resolved: 'channel',
+  ui_intent: 'react-side-effect',
+  session_renamed: 'react-side-effect',
+  history_cleared: 'channel',
+} as const satisfies Record<TInteractiveEventName, TTuiSessionEventClassification>;
+
+export interface ITuiSessionEventNotice {
+  id: string;
+  event:
+    | 'plan_event'
+    | 'context_file_refreshed'
+    | 'branch_event'
+    | 'delivery-error'
+    /** SCREEN-1992: TUI-originated — the interval recap on return, not a session event. */
+    | 'attention-recap';
+  message: string;
+}
+
+export type TTuiNoticeInput =
+  | { event: 'plan_event'; payload: IPlanApprovalEvent }
+  | { event: 'context_file_refreshed'; payload: IContextFileRefreshedEvent }
+  | { event: 'branch_event'; payload: IBranchEvent };
+
+/** Pure deterministic projection from domain event to TUI render state. */
+export function createTuiSessionEventNotice(
+  id: string,
+  input: TTuiNoticeInput,
+): ITuiSessionEventNotice {
+  switch (input.event) {
+    case 'plan_event':
+      return {
+        id,
+        event: input.event,
+        message: `Plan ${input.payload.type.replaceAll('_', ' ')}`,
+      };
+    case 'context_file_refreshed':
+      return {
+        id,
+        event: input.event,
+        message: `Context refreshed: ${input.payload.filePath}`,
+      };
+    case 'branch_event':
+      return {
+        id,
+        event: input.event,
+        message: `Branch ${input.payload.kind.replaceAll('_', ' ')}: ${input.payload.branchId} @ ${input.payload.checkpointId}`,
+      };
+  }
+}

package/src/tui-session-notice-store.ts

@@ -0,0 +1,43 @@
+import {
+  createTuiSessionEventNotice,
+  type ITuiSessionEventNotice,
+  type TTuiNoticeInput,
+} from './tui-session-events.js';
+
+import type { TInteractiveEventName } from '@robota-sdk/agent-interface-session';
+
+const NOTICE_LIMIT = 50;
+
+/** Bounded append-only render projection, deliberately separate from canonical session history. */
+export class TuiSessionNoticeStore {
+  private sequence = 0;
+  readonly notices: ITuiSessionEventNotice[] = [];
+
+  add(input: TTuiNoticeInput): void {
+    this.append(createTuiSessionEventNotice(this.nextId(), input));
+  }
+
+  addDeliveryError(error: Error, event: TInteractiveEventName): void {
+    this.append({
+      id: this.nextId(),
+      event: 'delivery-error',
+      message: `Session event delivery failed (${event}): ${error.message}`,
+    });
+  }
+
+  /** SCREEN-1992: one line for the unattended interval that just ended. */
+  addAttentionRecap(line: string): void {
+    this.append({ id: this.nextId(), event: 'attention-recap', message: line });
+  }
+
+  private nextId(): string {
+    this.sequence += 1;
+    return `session-event-${this.sequence}`;
+  }
+
+  private append(notice: ITuiSessionEventNotice): void {
+    this.notices.push(notice);
+    const overflow = this.notices.length - NOTICE_LIMIT;
+    if (overflow > 0) this.notices.splice(0, overflow);
+  }
+}

package/src/tui-session-options.ts

@@ -0,0 +1,118 @@
+/**
+ * ARCH-005 — the TUI's session-option mapping, split out of `TuiInteractionChannel`.
+ *
+ * Pure: it maps the channel's already-resolved options onto the framework's `TInteractiveSessionOptions`.
+ * RUNTIME-001 — the channel then builds through the shared `buildRuntimeSession` seam (agent-framework),
+ * never a private `new InteractiveSession`: one session-construction SSOT across the TUI, print, and
+ * `--serve`.
+ */
+
+import type { ITuiInteractionChannelOptions } from './tui-channel-options.js';
+import type { TInteractiveSessionOptions } from '@robota-sdk/agent-framework';
+
+/** Map the channel's resolved options onto the framework session-construction options. */
+export function buildTuiSessionOptions(
+  opts: ITuiInteractionChannelOptions,
+): TInteractiveSessionOptions {
+  return {
+    cwd: opts.cwd,
+    ...(opts.livePromptTrace ? { livePromptTrace: opts.livePromptTrace } : {}),
+    provider: opts.provider,
+    ...(opts.providerErrorGuidance !== undefined
+      ? { providerErrorGuidance: opts.providerErrorGuidance }
+      : {}),
+    ...(opts.promptFileReferenceTag !== undefined
+      ? { promptFileReferenceTag: opts.promptFileReferenceTag }
+      : {}),
+    ...(opts.modelCommandToolPrefix !== undefined
+      ? { modelCommandToolPrefix: opts.modelCommandToolPrefix }
+      : {}),
+    ...(opts.subagentHookEnvironmentNames !== undefined
+      ? { subagentHookEnvironmentNames: opts.subagentHookEnvironmentNames }
+      : {}),
+    ...(opts.observerFailureWarningCode !== undefined
+      ? { observerFailureWarningCode: opts.observerFailureWarningCode }
+      : {}),
+    ...(opts.commandHookShell !== undefined ? { commandHookShell: opts.commandHookShell } : {}),
+    ...(opts.bare === true ? { bare: true } : {}),
+    ...(opts.skipConfiguredHooks === true ? { skipConfiguredHooks: true } : {}),
+    ...(opts.orgPolicy !== undefined ? { orgPolicy: opts.orgPolicy } : {}),
+    ...(opts.projectAccess !== undefined ? { projectAccess: opts.projectAccess } : {}),
+    ...(opts.projectSettingsPaths !== undefined
+      ? { projectSettingsPaths: opts.projectSettingsPaths }
+      : {}),
+    ...(opts.baselinePermissionAllow !== undefined
+      ? { baselinePermissionAllow: opts.baselinePermissionAllow }
+      : {}),
+    ...(opts.taskContext !== undefined ? { taskContext: opts.taskContext } : {}),
+    ...(opts.contributionSources !== undefined
+      ? { contributionSources: opts.contributionSources }
+      : {}),
+    ...(opts.skillRoots !== undefined ? { skillRoots: opts.skillRoots } : {}),
+    ...(opts.userSettingsSources !== undefined
+      ? { userSettingsSources: opts.userSettingsSources }
+      : {}),
+    ...(opts.editCheckpointStore !== undefined
+      ? { editCheckpointStore: opts.editCheckpointStore }
+      : {}),
+    // 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 } : {}),
+    ...(opts.effort !== undefined ? { effort: opts.effort } : {}),
+    ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+    ...(opts.maxOutputTokens !== undefined ? { maxOutputTokens: opts.maxOutputTokens } : {}),
+    ...(opts.presetSystemPrompt !== undefined
+      ? { presetSystemPrompt: opts.presetSystemPrompt }
+      : {}),
+    ...(opts.responseFormat !== undefined ? { responseFormat: opts.responseFormat } : {}),
+    ...(opts.outputStyle !== undefined ? { outputStyle: opts.outputStyle } : {}),
+    permissionMode: opts.permissionMode,
+    maxTurns: opts.maxTurns,
+    // REMOTE-007: no injected permission/ask handlers — the TUI subscribes to the session's
+    // transport-neutral `permission_request`/`ask_request` events (wireSessionEvents) and answers via
+    // `resolvePermission`/`resolveAsk`. The local Ink queues + rendering are unchanged.
+    sessionStore: opts.sessionStore,
+    disableSessionLoops: opts.disableSessionLoops,
+    resolveDefaultLoopPrompt: opts.resolveDefaultLoopPrompt,
+    resumeSessionId: opts.resumeSessionId,
+    forkSession: opts.forkSession,
+    ...(opts.workspaceMovedFrom !== undefined
+      ? { workspaceMovedFrom: opts.workspaceMovedFrom }
+      : {}),
+    sessionName: opts.sessionName,
+    backgroundTaskRunners: opts.backgroundTaskRunners,
+    ...(opts.toolCallHandoff !== undefined ? { toolCallHandoff: opts.toolCallHandoff } : {}),
+    subagentRunnerFactory: opts.subagentRunnerFactory,
+    ...(opts.agentDefinitions !== undefined ? { agentDefinitions: opts.agentDefinitions } : {}),
+    ...(opts.agentDefinitionRoots !== undefined
+      ? { agentDefinitionRoots: opts.agentDefinitionRoots }
+      : {}),
+    ...(opts.pluginDirectories !== undefined ? { pluginDirectories: opts.pluginDirectories } : {}),
+    ...(opts.additionalTools !== undefined ? { additionalTools: opts.additionalTools } : {}),
+    ...(opts.defaultTools !== undefined ? { defaultTools: opts.defaultTools } : {}),
+    commandModules: opts.commandModules,
+    commandHostAdapters: opts.commandHostAdapters,
+    shellExec: opts.shellExec,
+    ...(opts.remoteCommandPolicy ? { remoteCommandPolicy: opts.remoteCommandPolicy } : {}),
+    language: opts.language,
+    agentName: opts.agentName,
+    activePresetId: opts.activePresetId,
+    persona: opts.persona,
+    systemPrompt: opts.systemPrompt,
+    appendSystemPrompt: opts.appendSystemPrompt,
+    allowedTools: opts.allowedTools,
+    deniedTools: opts.deniedTools,
+    enableParallelSubagents: opts.enableParallelSubagents,
+    selfVerification: opts.selfVerification,
+    terminalHandoff: opts.terminalHandoff,
+    // #1844: the session reads these when `/provider switch` hot-swaps. Absent, the switch throws
+    // "Unknown provider: <name>. Currently supported: " with an EMPTY list — measured, not inferred.
+    ...(opts.providerDefinitions ? { providerDefinitions: opts.providerDefinitions } : {}),
+    // SELFHOST-008 P6: forward the surface-resolved memory fields only when present (absent ⇒ OFF).
+    ...(opts.memoryStore ? { memoryStore: opts.memoryStore } : {}),
+    ...(opts.automaticMemory ? { automaticMemory: opts.automaticMemory } : {}),
+    ...(opts.recallMemory ? { recallMemory: opts.recallMemory } : {}),
+    // SCREEN-1993: the owner-prompt append (absent ⇒ the controller records nothing).
+    ...(opts.promptHistory ? { promptHistory: opts.promptHistory } : {}),
+  };
+}