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

package/src/PluginTUI.tsx

@@ -0,0 +1,258 @@
+/**
+ * PluginTUI — Main orchestrator component for plugin management.
+ * Manages a stack of screens: main, marketplace, installed plugins, etc.
+ */
+
+import React, { useState, useCallback } from 'react';
+
+import ConfirmPrompt from './ConfirmPrompt.js';
+import { usePluginScreenData } from './hooks/usePluginScreenData.js';
+import MenuSelect from './MenuSelect.js';
+import {
+  handleMainSelect,
+  handleMarketplaceListSelect,
+  handleMarketplaceActionSelect,
+  handleMarketplaceBrowseSelect,
+  handleInstallScopeSelect,
+  handleInstalledListSelect,
+  handleInstalledActionSelect,
+} from './plugin-tui-handlers.js';
+import TextPrompt from './TextPrompt.js';
+
+import type { IMenuSelectItem } from './MenuSelect.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-interface-command';
+
+type TScreenId =
+  | 'main'
+  | 'marketplace-list'
+  | 'marketplace-action'
+  | 'marketplace-browse'
+  | 'marketplace-install-scope'
+  | 'marketplace-add'
+  | 'installed-list'
+  | 'installed-action';
+
+interface IMenuContext {
+  marketplace?: string;
+  pluginId?: string;
+}
+
+interface IMenuState {
+  screen: TScreenId;
+  context?: IMenuContext;
+}
+
+interface IConfirmState {
+  message: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+interface IProps {
+  callbacks: ICommandPluginAdapter;
+  onClose: () => void;
+  addMessage?: (msg: { role: string; content: string }) => void;
+}
+
+export default function PluginTUI({ callbacks, onClose, addMessage }: IProps): React.ReactElement {
+  const [stack, setStack] = useState<IMenuState[]>([{ screen: 'main' }]);
+  const [confirm, setConfirm] = useState<IConfirmState | undefined>();
+  const [refreshCounter, setRefreshCounter] = useState(0);
+
+  const current = stack[stack.length - 1] ?? { screen: 'main' };
+
+  const push = useCallback((state: IMenuState) => {
+    setStack((prev) => [...prev, state]);
+  }, []);
+
+  const pop = useCallback(() => {
+    setStack((prev) => {
+      if (prev.length <= 1) {
+        onClose();
+        return prev;
+      }
+      return prev.slice(0, -1);
+    });
+  }, [onClose]);
+
+  const popN = useCallback(
+    (n: number) => {
+      setStack((prev) => {
+        const next = prev.slice(0, Math.max(1, prev.length - n));
+        if (next.length === 0) {
+          onClose();
+          return prev;
+        }
+        return next;
+      });
+    },
+    [onClose],
+  );
+
+  const notify = useCallback(
+    (content: string) => {
+      addMessage?.({ role: 'system', content });
+    },
+    [addMessage],
+  );
+
+  const refresh = useCallback(() => {
+    setRefreshCounter((c) => c + 1);
+  }, []);
+
+  const setConfirmNav = useCallback(
+    (state: IConfirmState | undefined) => setConfirm(state),
+    [setConfirm],
+  );
+  // nav.push accepts a loose { screen: string } shape to satisfy plugin-tui-handlers types;
+  // we cast screen to TScreenId which is safe because handlers only push valid screen names.
+  const pushNav = useCallback(
+    (state: { screen: string; context?: IMenuContext }) =>
+      push({ screen: state.screen as TScreenId, context: state.context }),
+    [push],
+  );
+  const nav = { push: pushNav, pop, popN, notify, setConfirm: setConfirmNav, refresh };
+
+  const { items, loading, error } = usePluginScreenData(
+    current.screen,
+    current.context?.marketplace,
+    callbacks,
+    refreshCounter,
+    stack.length,
+  );
+
+  const handleSelect = useCallback(
+    (value: string) => {
+      const screen = current.screen;
+      const ctx = current.context;
+
+      if (screen === 'main') handleMainSelect(value, nav);
+      else if (screen === 'marketplace-list') handleMarketplaceListSelect(value, nav);
+      else if (screen === 'marketplace-action')
+        handleMarketplaceActionSelect(value, ctx?.marketplace ?? '', callbacks, nav);
+      else if (screen === 'marketplace-browse')
+        handleMarketplaceBrowseSelect(value, ctx?.marketplace ?? '', items, nav);
+      else if (screen === 'marketplace-install-scope')
+        handleInstallScopeSelect(value, ctx?.pluginId ?? '', callbacks, nav);
+      else if (screen === 'installed-list') handleInstalledListSelect(value, callbacks, nav);
+      else if (screen === 'installed-action')
+        handleInstalledActionSelect(value, ctx?.pluginId ?? '', callbacks, nav);
+    },
+    [current, items, callbacks, push, pop, popN, notify, setConfirm, refresh],
+  );
+
+  const handleTextSubmit = useCallback(
+    (value: string) => {
+      if (current.screen === 'marketplace-add') {
+        callbacks
+          .marketplaceAdd(value)
+          .then((name) => {
+            notify(`Added marketplace "${name}" from ${value}.`);
+            pop();
+          })
+          .catch((err) => {
+            notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            pop();
+          });
+      }
+    },
+    [current.screen, callbacks, notify, pop],
+  );
+
+  // Confirm overlay intercepts everything
+  if (confirm) {
+    return (
+      <ConfirmPrompt
+        message={confirm.message}
+        onSelect={(index) => {
+          if (index === 0) confirm.onConfirm();
+          else confirm.onCancel();
+        }}
+      />
+    );
+  }
+
+  const screen = current.screen;
+
+  if (screen === 'marketplace-add') {
+    return (
+      <TextPrompt
+        title="Add Marketplace Source"
+        placeholder="owner/repo or git URL"
+        onSubmit={handleTextSubmit}
+        onCancel={pop}
+        validate={(v) => (!v.includes('/') ? 'Must be owner/repo or a git URL' : undefined)}
+      />
+    );
+  }
+
+  if (screen === 'marketplace-action') {
+    return (
+      <MenuSelect
+        key={stack.length}
+        title={`Marketplace: ${current.context?.marketplace ?? ''}`}
+        items={[
+          { label: 'Browse plugins', value: 'browse' },
+          { label: 'Update', value: 'update' },
+          { label: 'Remove', value: 'remove' },
+        ]}
+        onSelect={handleSelect}
+        onBack={pop}
+      />
+    );
+  }
+
+  if (screen === 'marketplace-install-scope') {
+    return (
+      <MenuSelect
+        key={stack.length}
+        title={`Install scope for "${current.context?.pluginId ?? ''}"`}
+        items={[
+          { label: 'User scope', value: 'user' },
+          { label: 'Project scope', value: 'project' },
+        ]}
+        onSelect={handleSelect}
+        onBack={pop}
+      />
+    );
+  }
+
+  if (screen === 'installed-action') {
+    return (
+      <MenuSelect
+        key={stack.length}
+        title={`Plugin: ${current.context?.pluginId ?? ''}`}
+        items={[{ label: 'Uninstall', value: 'uninstall' }]}
+        onSelect={handleSelect}
+        onBack={pop}
+      />
+    );
+  }
+
+  // Screens with async items: main, marketplace-list, marketplace-browse, installed-list
+  const titleMap: Record<string, string> = {
+    main: 'Plugin Management',
+    'marketplace-list': 'Marketplace',
+    'marketplace-browse': `Browse: ${current.context?.marketplace ?? ''}`,
+    'installed-list': 'Installed Plugins',
+  };
+
+  const staticItemsMap: Record<string, IMenuSelectItem[]> = {
+    main: [
+      { label: 'Marketplace', value: 'marketplace' },
+      { label: 'Installed Plugins', value: 'installed' },
+    ],
+  };
+
+  return (
+    <MenuSelect
+      key={`${screen}-${stack.length}-${refreshCounter}`}
+      title={titleMap[screen] ?? 'Plugin Management'}
+      items={staticItemsMap[screen] ?? items}
+      onSelect={handleSelect}
+      onBack={pop}
+      loading={loading}
+      error={error}
+    />
+  );
+}

package/src/RoleLabel.tsx

@@ -0,0 +1,72 @@
+import { OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { useProductDisplayName } from './product-display-name-context.js';
+import { useScreenReader } from './screen-reader-context.js';
+import { screenReaderLabelForRole } from './screen-reader-labels.js';
+import { usePalette } from './theme/index.js';
+
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+/**
+ * Who a transcript line is attributed to, and in what colour. Extracted from MessageList when
+ * PEER-007 gave the `user` case a second thing to decide: the label stopped being a constant per
+ * role, so it is its own responsibility rather than four inline returns.
+ */
+
+/**
+ * PEER-007 (issue #1915): the operator's own turns stay `You:`; a turn driven by anyone else is
+ * labelled with WHO drove it, so a co-driven transcript can be read after the fact. `owner` is the
+ * operator, so it reads as `You:` too; anything else prints as itself (`peer:<session-id>`, `agent`).
+ */
+function driverLabel(driverId: string): string {
+  return driverId === OWNER_DRIVER_ID ? 'You' : driverId;
+}
+
+export function RoleLabel({
+  role,
+  driverId,
+}: {
+  role: TUniversalMessage['role'];
+  driverId?: string;
+}): React.ReactElement {
+  const palette = usePalette();
+  const screenReader = useScreenReader();
+  const productDisplayName = useProductDisplayName();
+  if (screenReader) {
+    // CLI-2004: the label comes from the ROLE, never the vendor — `assistant:` under every
+    // agent-provider-*. No colour: in this mode the searchable word is the whole cue.
+    const label =
+      role === 'user' && driverId !== undefined && driverId !== OWNER_DRIVER_ID
+        ? `${driverId}:`
+        : screenReaderLabelForRole(role);
+    return <Text>{label} </Text>;
+  }
+  switch (role) {
+    case 'user':
+      return (
+        <Text color={palette.text.success} bold>
+          {driverId !== undefined ? driverLabel(driverId) : 'You'}:{' '}
+        </Text>
+      );
+    case 'assistant':
+      return (
+        <Text color={palette.text.accent} bold>
+          {productDisplayName}:{' '}
+        </Text>
+      );
+    case 'system':
+      return (
+        <Text color={palette.text.warning} bold>
+          System:{' '}
+        </Text>
+      );
+    case 'tool':
+      return (
+        <Text color={palette.text.emphasis} bold>
+          Tool:{' '}
+        </Text>
+      );
+  }
+}

package/src/SafeText.tsx

@@ -0,0 +1,66 @@
+/**
+ * `SafeText` — the ONE way a string reaches the terminal from this package (#2222).
+ *
+ * SEC-019 fixed every render site that was found to put untrusted text — model output, tool stdout,
+ * file contents, plugin-supplied names — on the terminal through Ink's `<Text>`. Six review rounds
+ * found three sites nobody had covered, because "sanitized" was a property of individual lines of
+ * code, and a site added later by someone who never read SEC-019 is covered by nothing.
+ *
+ * This component makes the boundary structural: every string child is passed through
+ * `sanitizeTerminalText` before Ink sees it, and the `tui-safe-text-boundary` scan refuses any other
+ * module in this package that imports `Text` from `ink` — plain, aliased, or through a namespace.
+ * A render site therefore CANNOT put a string on the terminal without passing through here. For the
+ * many constant labels this is a no-op; that is the point — the boundary is not "the sites judged
+ * to carry untrusted text", because that judgement is what already failed twice.
+ *
+ * This module is the only permitted importer of Ink's `Text`.
+ */
+
+import { Text as InkText } from 'ink';
+import React from 'react';
+
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+
+import type { ReactNode } from 'react';
+
+type TInkTextProps = React.ComponentProps<typeof InkText>;
+
+function sanitizeChildren(children: ReactNode): ReactNode {
+  if (typeof children === 'string') return sanitizeTerminalText(children);
+  if (typeof children === 'number' || typeof children === 'boolean') return children;
+  if (children === null || children === undefined) return children;
+  if (Array.isArray(children)) return children.map((child) => sanitizeChildren(child));
+  // A nested element (another <Text>, a <Box>) sanitizes its own string children on its own render.
+  return children;
+}
+
+/** Ink's `Text`, with every string child sanitized for the terminal. Same props, same output shape. */
+export function SafeText(props: TInkTextProps): React.JSX.Element {
+  const { children, ...rest } = props;
+  return <InkText {...rest}>{sanitizeChildren(children)}</InkText>;
+}
+
+/**
+ * Ink's `Text` for a string THIS PACKAGE'S OWN RENDERER produced from already-sanitized input.
+ *
+ * `renderMarkdown` sanitizes the untrusted markdown BEFORE `marked-terminal` styles it, and the
+ * SGR colour in its output (the theme's diff pairs, heading emphasis) is the renderer's
+ * own, not the model's. Routing that output through `SafeText` would strip the styling the renderer
+ * just applied — the SCREEN-006 diff colours vanished exactly that way. The boundary still holds:
+ * the only string that reaches this component is one the renderer built from sanitized text, and
+ * the `tui-safe-text-boundary` scan keeps every other module off Ink's `Text`.
+ *
+ * PERMITTED here: a string this package's own renderer built from already-sanitized input — today
+ * that is exactly `renderMarkdown(...)`, which sanitizes before it styles. FORBIDDEN here: any
+ * string that has not passed a sanitizer — raw model output, tool stdout, file contents, plugin
+ * names, a template that interpolates one of those — which goes through `SafeText`/`Text` instead.
+ * The mirror rule holds too: `renderMarkdown(...)` must NOT be a child of `SafeText`/`Text`, whose
+ * sanitizer would strip the renderer's own SGR. The `tui-safe-text-boundary` scan enforces both
+ * directions, so neither is left to a reviewer noticing it.
+ */
+export function RenderedText(props: TInkTextProps): React.JSX.Element {
+  return <InkText {...props} />;
+}
+
+/** Call sites keep writing `<Text>`; the name resolves to the boundary rather than to Ink. */
+export { SafeText as Text };

package/src/SessionEventNotices.tsx

@@ -0,0 +1,27 @@
+import { Box } from 'ink';
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+import type { ITuiSessionEventNotice } from './tui-session-events.js';
+
+export interface ISessionEventNoticesProps {
+  notices: readonly ITuiSessionEventNotice[];
+}
+
+export default function SessionEventNotices({
+  notices,
+}: ISessionEventNoticesProps): React.ReactElement | null {
+  const palette = usePalette();
+  if (notices.length === 0) return null;
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      {notices.map((notice) => (
+        <Text key={notice.id} color={palette.text.muted}>
+          {notice.message}
+        </Text>
+      ))}
+    </Box>
+  );
+}

package/src/SessionPicker.tsx

@@ -0,0 +1,72 @@
+/**
+ * Session picker component for /resume command.
+ * Shows a list of sessions for the current cwd.
+ */
+
+import { Box } from 'ink';
+import React from 'react';
+
+import { SELECTION_INDICATOR, SELECTION_INDICATOR_NONE } from './key-hint-footer.js';
+import ListPicker from './ListPicker.js';
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+
+import type { IResumableSessionSummary } from '@robota-sdk/agent-interface-session';
+
+const SESSION_ID_DISPLAY_LENGTH = 8;
+const SESSION_PREVIEW_DISPLAY_LENGTH = 60;
+
+interface IProps {
+  sessions: readonly IResumableSessionSummary[];
+  onSelect: (sessionId: string) => void;
+  onCancel: () => void;
+}
+
+export default function SessionPicker({
+  sessions,
+  onSelect,
+  onCancel,
+}: IProps): React.ReactElement {
+  const palette = usePalette();
+  return (
+    <Box flexDirection="column" paddingX={1} marginBottom={1}>
+      <Text bold color={palette.text.accent}>
+        Select a session to resume:
+      </Text>
+      <ListPicker<IResumableSessionSummary>
+        items={[...sessions]}
+        renderItem={(session: IResumableSessionSummary, isSelected: boolean) => {
+          const preview = session.preview
+            ? session.preview.slice(0, SESSION_PREVIEW_DISPLAY_LENGTH) +
+              (session.preview.length > SESSION_PREVIEW_DISPLAY_LENGTH ? '...' : '')
+            : '';
+          return (
+            <Text>
+              {isSelected ? SELECTION_INDICATOR : SELECTION_INDICATOR_NONE}
+              <Text bold>{session.name ?? session.id.slice(0, SESSION_ID_DISPLAY_LENGTH)}</Text>
+              {'  '}
+              <Text dimColor>
+                {new Date(session.updatedAt).toLocaleString(undefined, {
+                  month: 'short',
+                  day: 'numeric',
+                  hour: '2-digit',
+                  minute: '2-digit',
+                })}
+              </Text>
+              {'  '}
+              <Text dimColor>msgs: {session.messageCount}</Text>
+              {preview ? (
+                <>
+                  {'\n    '}
+                  <Text dimColor>{preview}</Text>
+                </>
+              ) : null}
+            </Text>
+          );
+        }}
+        onSelect={(session: IResumableSessionSummary) => onSelect(session.id)}
+        onCancel={onCancel}
+      />
+    </Box>
+  );
+}

package/src/SessionStatusBar.tsx

@@ -0,0 +1,76 @@
+import React, { useMemo } from 'react';
+
+import StatusBar from './StatusBar.js';
+import { useTuiCliAdapter } from './tui-cli-adapter-context.js';
+
+import type { TModelEffortSelection, TPermissionMode } from '@robota-sdk/agent-core';
+import type { IStatusLineCommandSettings } from '@robota-sdk/agent-interface-command';
+
+interface IProps {
+  cwd: string;
+  permissionMode: TPermissionMode;
+  modelId?: string;
+  providerType?: string | undefined;
+  sessionId: string;
+  isThinking: boolean;
+  activeToolCount: number;
+  activeBackgroundTaskCount: number;
+  hasPendingPrompt: boolean;
+  contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  sessionName?: string;
+  settings: IStatusLineCommandSettings;
+  activeAgentLabel?: string;
+  activePresetId?: string;
+  effort?: TModelEffortSelection;
+  gitRefreshToken?: number;
+}
+
+export default function SessionStatusBar({
+  cwd,
+  permissionMode,
+  modelId,
+  providerType,
+  sessionId,
+  isThinking,
+  activeToolCount,
+  activeBackgroundTaskCount,
+  hasPendingPrompt,
+  contextState,
+  sessionName,
+  settings,
+  activeAgentLabel,
+  activePresetId,
+  effort,
+  gitRefreshToken,
+}: IProps): React.ReactElement | null {
+  const cliAdapter = useTuiCliAdapter();
+  const gitBranch = useMemo(() => cliAdapter.getGitBranch(cwd), [cliAdapter, cwd, gitRefreshToken]);
+  const providerDisplayName = useMemo(
+    () =>
+      providerType !== undefined ? cliAdapter.getProviderDisplayName(providerType) : undefined,
+    [cliAdapter, providerType],
+  );
+  if (!settings.enabled) return null;
+
+  return (
+    <StatusBar
+      permissionMode={permissionMode}
+      modelName={modelId ?? ''}
+      providerDisplayName={providerDisplayName}
+      sessionId={sessionId}
+      isThinking={isThinking}
+      activeToolCount={activeToolCount}
+      activeBackgroundTaskCount={activeBackgroundTaskCount}
+      hasPendingPrompt={hasPendingPrompt}
+      contextPercentage={contextState.percentage}
+      contextUsedTokens={contextState.usedTokens}
+      contextMaxTokens={contextState.maxTokens}
+      sessionName={sessionName}
+      gitBranch={gitBranch}
+      showGitBranch={settings.gitBranch}
+      activeAgentLabel={activeAgentLabel}
+      activePresetId={activePresetId}
+      effort={effort}
+    />
+  );
+}