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

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@robota-sdk/agent-ui-terminal",
+  "version": "3.0.0-beta.81",
+  "description": "Terminal UI package (React + Ink) for the Robota SDK",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota.git"
+  },
+  "homepage": "https://robota.io/",
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "ink": "^7.1.1",
+    "marked": "^9.1.6",
+    "marked-terminal": "^7.3.0",
+    "react": "19.2.8",
+    "string-width": "^8.2.2",
+    "@robota-sdk/agent-core": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-analytics": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.81",
+    "@robota-sdk/agent-framework": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-tui": "3.0.0-beta.81",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.81"
+  },
+  "devDependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "^0.14.1",
+    "@types/react": "^19.2.17",
+    "ink-testing-library": "^4.0.0",
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6",
+    "@robota-sdk/agent-command": "3.0.0-beta.81"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit && tsgo -p tsconfig.examples.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "scenario:verify": "pnpm exec tsx --conditions=source examples/verify-session-event-rendering.ts",
+    "test:pty": "vitest run --config vitest.pty.config.ts",
+    "clean": "rimraf dist"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,146 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import AppView from './AppView.js';
+import { TuiCliAdapterProvider } from './tui-cli-adapter-context.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 { TPermissionMode } from '@robota-sdk/agent-core';
+import type { TReducedMotionOverride } from '@robota-sdk/agent-interface-command';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+import type { IInteractiveSessionStore } from '@robota-sdk/agent-interface-session';
+import type { IPromptHistorySource } from '@robota-sdk/agent-interface-session';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+
+interface IProps {
+  cwd: string;
+  /** The composition root narrows every concrete channel to this port before React receives it. */
+  createChannel: (resumeSessionId?: string) => ITuiAppChannelPort;
+  providerOverride?: string | undefined;
+  providerType?: string | undefined;
+  modelId?: string;
+  permissionMode?: TPermissionMode;
+  version?: string;
+  sessionStore?: IInteractiveSessionStore;
+  resumeSessionId?: string;
+  showSessionPickerOnStart?: boolean;
+  /** FLOW-2006: a deep link's prefill, consumed once by the composer. */
+  initialInput?: string;
+  initialInputOrigin?: 'external-link';
+  startupUpdateNotice?: Promise<string | undefined>;
+  transportRegistry?: ITransportRegistryView;
+  pluginAdapter?: ICommandPluginAdapter;
+  cliAdapter: ITuiCliAdapter;
+  /** SCREEN-1993: the stored-prompt source and project key for the input area's search. */
+  promptHistorySource?: IPromptHistorySource;
+  promptHistoryProject?: string;
+  /** SCREEN-2002: the theme catalogue this run renders from; absent ⇒ the built-ins. */
+  themeRegistry?: IThemeRegistry;
+  /** SCREEN-2002: reduced motion as the product shell resolved it (settings ← env ← flag). */
+  reducedMotion?: boolean | undefined;
+  /** SCREEN-2002: which tier decided it, when that was not the settings. */
+  reducedMotionOverride?: TReducedMotionOverride | undefined;
+}
+
+interface IActiveChannel {
+  readonly state: { channel: ITuiAppChannelPort; sessionId: string | undefined };
+  readonly showPicker: boolean;
+  readonly error: string | undefined;
+  readonly switching: boolean;
+  readonly switchSession: (sessionId: string) => Promise<void>;
+  readonly retrySwitch: () => void;
+}
+
+function useActiveChannel(props: IProps): IActiveChannel {
+  const [state, setState] = useState(() => ({
+    channel: props.createChannel(props.resumeSessionId),
+    sessionId: props.resumeSessionId,
+  }));
+  const [showPicker, setShowPicker] = useState(props.showSessionPickerOnStart ?? false);
+  const [error, setError] = useState<string | undefined>();
+  const [isSwitching, setIsSwitching] = useState(false);
+  const [failedTarget, setFailedTarget] = useState<string | undefined>();
+  const switching = useRef(false);
+  const mounted = useRef(true);
+  useEffect(
+    () => () => {
+      mounted.current = false;
+    },
+    [],
+  );
+  const switchSession = useCallback(
+    async (sessionId: string): Promise<void> => {
+      if (switching.current) return;
+      switching.current = true;
+      setIsSwitching(true);
+      try {
+        setShowPicker(false);
+        await state.channel.stop();
+        if (!mounted.current) return;
+        setState({ channel: props.createChannel(sessionId), sessionId });
+        setFailedTarget(undefined);
+        setError(undefined);
+      } catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        setError(`Session switch failed: ${message}`);
+        setFailedTarget(sessionId);
+      } finally {
+        switching.current = false;
+        setIsSwitching(false);
+      }
+    },
+    [props.createChannel, state.channel],
+  );
+  const retrySwitch = useCallback((): void => {
+    if (failedTarget !== undefined) void switchSession(failedTarget);
+  }, [failedTarget, switchSession]);
+  return { state, showPicker, error, switching: isSwitching, switchSession, retrySwitch };
+}
+
+/** React composition shell. Concrete framework objects stay outside the React tree. */
+export default function App(props: IProps): React.ReactElement {
+  const active = useActiveChannel(props);
+
+  return (
+    <TuiCliAdapterProvider value={props.cliAdapter}>
+      <AppView
+        key={active.state.sessionId ?? '__new__'}
+        cwd={props.cwd}
+        channel={active.state.channel}
+        onSessionSwitch={active.switchSession}
+        onRetrySessionSwitch={active.retrySwitch}
+        sessionSwitchError={active.error}
+        sessionSwitchPending={active.switching}
+        showSessionPickerOnStart={active.showPicker}
+        {...(props.initialInput !== undefined ? { initialInput: props.initialInput } : {})}
+        {...(props.initialInputOrigin !== undefined
+          ? { initialInputOrigin: props.initialInputOrigin }
+          : {})}
+        {...(props.providerType !== undefined ? { providerType: props.providerType } : {})}
+        {...(props.modelId !== undefined ? { modelId: props.modelId } : {})}
+        {...(props.permissionMode !== undefined ? { permissionMode: props.permissionMode } : {})}
+        {...(props.version !== undefined ? { version: props.version } : {})}
+        {...(props.sessionStore !== undefined ? { sessionStore: props.sessionStore } : {})}
+        {...(props.startupUpdateNotice !== undefined
+          ? { startupUpdateNotice: props.startupUpdateNotice }
+          : {})}
+        {...(props.transportRegistry !== undefined
+          ? { transportRegistry: props.transportRegistry }
+          : {})}
+        {...(props.pluginAdapter !== undefined ? { pluginAdapter: props.pluginAdapter } : {})}
+        {...(props.promptHistorySource !== undefined
+          ? { promptHistorySource: props.promptHistorySource }
+          : {})}
+        {...(props.promptHistoryProject !== undefined
+          ? { promptHistoryProject: props.promptHistoryProject }
+          : {})}
+        {...(props.themeRegistry !== undefined ? { themeRegistry: props.themeRegistry } : {})}
+        {...(props.reducedMotion !== undefined ? { reducedMotion: props.reducedMotion } : {})}
+        {...(props.reducedMotionOverride !== undefined
+          ? { reducedMotionOverride: props.reducedMotionOverride }
+          : {})}
+      />
+    </TuiCliAdapterProvider>
+  );
+}

package/src/AppPresentation.tsx

@@ -0,0 +1,190 @@
+import { Box, Static } from 'ink';
+import React from 'react';
+
+import { AppBanner } from './app-banner.js';
+import BackgroundTaskPanel from './BackgroundTaskPanel.js';
+import { ContextWarningBanner } from './ContextWarningBanner.js';
+import ExecutionWorkspaceDetailPane from './ExecutionWorkspaceDetailPane.js';
+import ExecutionWorkspaceSwitcher from './ExecutionWorkspaceSwitcher.js';
+import InputArea from './InputArea.js';
+import { useKeybindings } from './keybindings/keybindings-context.js';
+import { EntryItem } from './MessageList.js';
+import PendingActionPrompt from './PendingActionPrompt.js';
+import PermissionPrompt from './PermissionPrompt.js';
+import PluginTUI from './PluginTUI.js';
+import { Text } from './SafeText.js';
+import SessionEventNotices from './SessionEventNotices.js';
+import SessionPicker from './SessionPicker.js';
+import SessionStatusBar from './SessionStatusBar.js';
+import StreamingIndicator from './StreamingIndicator.js';
+import { usePalette } from './theme/index.js';
+import ThemePicker from './ThemePicker.js';
+import TransportTUI from './TransportTUI.js';
+import UpdateNotice from './UpdateNotice.js';
+
+import type { IAppViewModel } from './app-view-model.js';
+
+function Transcript({ model }: { model: IAppViewModel }): React.ReactElement {
+  return (
+    <Static items={model.staticItems}>
+      {(item) =>
+        item.kind === 'banner' ? (
+          <AppBanner key="logo" version={item.version} />
+        ) : (
+          <EntryItem key={item.entry.id} entry={item.entry} />
+        )
+      }
+    </Static>
+  );
+}
+
+function Activity({ model }: { model: IAppViewModel }): React.ReactElement {
+  const palette = usePalette();
+  const { background, stream } = model;
+  return (
+    <Box flexDirection="column" paddingX={1} flexGrow={1}>
+      {background.selectedEntry && background.selectedEntry.kind !== 'main_thread' && (
+        <ExecutionWorkspaceDetailPane
+          entry={background.selectedEntry}
+          page={background.detail.page}
+          loading={background.detail.loading}
+          error={background.detail.error}
+        />
+      )}
+      {model.isShuttingDown && <Text color={palette.text.warning}>Shutting down...</Text>}
+      {(stream.isThinking || stream.activeTools.length > 0) && (
+        <Box flexDirection="column" marginBottom={1}>
+          <StreamingIndicator
+            text={stream.text}
+            activeTools={stream.activeTools}
+            isThinking={stream.isThinking}
+          />
+          {stream.isStalled && (
+            <Text color={palette.text.warning}>
+              ⚠ Still waiting on the provider — the network may be stalled. Esc to interrupt.
+            </Text>
+          )}
+        </Box>
+      )}
+      {!stream.isThinking && stream.lastErrorMessage && (
+        <Text color={palette.text.error}>
+          ✖ Last turn failed — the session is alive; type your next prompt when ready.
+        </Text>
+      )}
+      <BackgroundTaskPanel entries={background.entries} focusedIndex={background.focusedIndex} />
+    </Box>
+  );
+}
+
+function Overlays({ model }: { model: IAppViewModel }): React.ReactElement {
+  if (model.coordinationError !== undefined || model.coordinationPending) return <></>;
+  const { background, plugin, sessionPicker, transport } = model;
+  const pendingUserAction = model.pendingUserAction;
+  return (
+    <>
+      {background.switcherVisible && (
+        <ExecutionWorkspaceSwitcher
+          snapshot={background.snapshot}
+          selectedEntryId={background.selectedEntryId}
+          onSelect={background.select}
+          onClose={background.closeSwitcher}
+          onAttach={background.attachToFork}
+        />
+      )}
+      {model.permissionRequest && <PermissionPrompt request={model.permissionRequest} />}
+      {pendingUserAction && (
+        <PendingActionPrompt
+          request={pendingUserAction}
+          onAnswer={(response) => model.resolveUserAction(pendingUserAction, response)}
+        />
+      )}
+      {plugin.visible && (
+        <PluginTUI
+          callbacks={plugin.callbacks}
+          onClose={plugin.close}
+          addMessage={(message) => plugin.addMessage(message.content)}
+        />
+      )}
+      {transport.visible && transport.registry && (
+        <TransportTUI registry={transport.registry} onClose={transport.close} />
+      )}
+      {sessionPicker.visible && (
+        <SessionPicker
+          sessions={sessionPicker.sessions}
+          onSelect={sessionPicker.select}
+          onCancel={sessionPicker.cancel}
+        />
+      )}
+      {model.theme.picker.visible && <ThemePicker picker={model.theme.picker} />}
+    </>
+  );
+}
+
+function PromptAndStatus({ model }: { model: IAppViewModel }): React.ReactElement {
+  const { input } = model;
+  return (
+    <>
+      <ContextWarningBanner percentage={model.contextPercentage} />
+      <InputArea
+        onSubmit={input.submit}
+        onCancelQueue={input.cancelQueue}
+        isDisabled={input.disabled}
+        isQueueCancellationDisabled={input.queueCancellationDisabled}
+        isAborting={input.isAborting}
+        pendingPrompt={input.pendingPrompt}
+        pendingCount={input.pendingCount}
+        commandQueryPort={input.commandQueryPort}
+        sessionName={input.sessionName}
+        history={input.history}
+        onRequestFocusBackgroundList={input.focusBackgroundList}
+        historySearch={input.historySearch}
+        initialValue={input.initialValue}
+        consumeInitialValue={input.consumeInitialValue}
+        externalPromptOrigin={input.externalPromptOrigin}
+      />
+      <SessionStatusBar {...model.status} />
+    </>
+  );
+}
+
+/** Pure presentation tree: it receives no channel, session, registry, or mutable state manager. */
+export default function AppPresentation({
+  viewModel,
+}: {
+  viewModel: IAppViewModel;
+}): React.ReactElement {
+  const palette = usePalette();
+  const keybindings = useKeybindings();
+  return (
+    <Box flexDirection="column">
+      <Transcript model={viewModel} />
+      {!viewModel.handoffSuspended && (
+        <>
+          {viewModel.updateNotice && <UpdateNotice message={viewModel.updateNotice} />}
+          {viewModel.coordinationError && (
+            <Text color={palette.text.error}>
+              {viewModel.coordinationError} Press Enter to retry.
+            </Text>
+          )}
+          {keybindings.diagnostic && (
+            <Text color={palette.text.error}>
+              {`Keybindings ${keybindings.diagnostic.file} ${keybindings.diagnostic.path}: ${keybindings.diagnostic.message} Last valid bindings remain active.`}
+            </Text>
+          )}
+          {keybindings.warnings.map((warning) => (
+            <Text key={`${warning.path}:${warning.code}`} color={palette.text.warning}>
+              {`Keybindings ${warning.path}: ${warning.message}`}
+            </Text>
+          ))}
+          {viewModel.theme.unknownThemeNotice !== undefined && (
+            <Text color={palette.text.warning}>{viewModel.theme.unknownThemeNotice}</Text>
+          )}
+          <SessionEventNotices notices={viewModel.sessionEventNotices} />
+          <Activity model={viewModel} />
+          <Overlays model={viewModel} />
+          <PromptAndStatus model={viewModel} />
+        </>
+      )}
+    </Box>
+  );
+}

package/src/AppView.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+import AppPresentation from './AppPresentation.js';
+import { useAppController } from './hooks/useAppController.js';
+import { ThemeProvider } from './theme/index.js';
+
+import type { IUseAppControllerOptions } from './hooks/useAppController.js';
+
+export type IAppViewProps = IUseAppControllerOptions;
+
+/** Controller boundary: the channel terminates here and only a view model reaches presentation. */
+export default function AppView(props: IAppViewProps): React.ReactElement {
+  const viewModel = useAppController(props);
+  // SCREEN-2002: the provider sits HERE rather than above the controller, because the resolved
+  // theme is part of the view model — a provider higher up would have to be fed a theme nobody had
+  // resolved yet, and the controller's own hooks read no colours.
+  return (
+    <ThemeProvider
+      theme={viewModel.theme.resolved}
+      reducedMotion={viewModel.theme.reducedMotion}
+      syntaxHighlighting={viewModel.theme.syntaxHighlighting}
+    >
+      <AppPresentation viewModel={viewModel} />
+    </ThemeProvider>
+  );
+}

package/src/BackgroundTaskPanel.tsx

@@ -0,0 +1,73 @@
+import { Box } from 'ink';
+import React from 'react';
+
+import { formatBackgroundTaskRow } from './background-task-row-format.js';
+import { useCountdownTick } from './hooks/useCountdownTick.js';
+import { Text } from './SafeText.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { statusGlyphColor } from './status-glyph.js';
+import { usePalette } from './theme/index.js';
+
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+
+interface IProps {
+  entries: IExecutionWorkspaceEntry[];
+  /** Index of the keyboard-focused row (SCREEN-014), or null when the prompt input is focused. */
+  focusedIndex?: number | null;
+}
+
+export default function BackgroundTaskPanel({
+  entries,
+  focusedIndex = null,
+}: IProps): React.ReactElement | null {
+  const palette = usePalette();
+  const screenReader = useScreenReader();
+  // SCREEN-1992: ticks once a second only while a schedule sleeps, never in screen-reader mode.
+  const now = useCountdownTick(
+    entries.some((entry) => entry.nextFireAt !== undefined),
+    screenReader,
+  );
+  if (entries.length === 0) return null;
+
+  // SCREEN-014: the hint is focus-aware — it tells you how to enter the list, then how to move/open.
+  const hint =
+    focusedIndex !== null ? '  ·  ↑↓ select · Enter open · Esc back' : '  ·  ↓ select · Ctrl+B all';
+
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <Text color={palette.text.accent} bold>
+          Background work
+        </Text>
+        <Text dimColor>{hint}</Text>
+      </Box>
+      {entries.map((entry, index) => {
+        const row = formatBackgroundTaskRow(entry, {
+          isLast: index === entries.length - 1,
+          screenReader,
+          now,
+        });
+        const isFocused = index === focusedIndex;
+        return (
+          // SCREEN-011: one truncated line so the connector + glyph lead the row.
+          // SCREEN-014: the keyboard-focused row is inverse-highlighted.
+          <Text key={entry.id} wrap="truncate-end" inverse={isFocused}>
+            {`${row.connector} `}
+            <Text
+              color={statusGlyphColor(palette, row.statusKind)}
+            >{`${row.marker} ${row.state}`}</Text>
+            {` ${row.label}`}
+            {row.segments.map((segment, segmentIndex) => (
+              <Text key={`${segment}-${segmentIndex}`} dimColor>{` · ${segment}`}</Text>
+            ))}
+            {row.headline ? <Text dimColor>{` · ${row.headline}`}</Text> : null}
+            {row.preview ? <Text dimColor>{` · ${row.preview}`}</Text> : null}
+            {row.countdown ? (
+              <Text color={statusGlyphColor(palette, row.statusKind)}>{` · ${row.countdown}`}</Text>
+            ) : null}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}