@robota-sdk/agent-transport 3.0.0-beta.64

package/src/tui/hooks/useSlashRouting.ts

@@ -0,0 +1,117 @@
+/**
+ * Slash command routing logic for the TUI.
+ * Extracted from useInteractiveSession for single-responsibility.
+ */
+
+import { useCallback } from 'react';
+import type {
+  IInteractiveSession,
+  CommandRegistry,
+  ICommandResult,
+  TCommandEffect,
+} from '@robota-sdk/agent-framework';
+import { createSystemMessage, messageToHistoryEntry } from '@robota-sdk/agent-core';
+import type { TuiStateManager } from '../tui-state-manager.js';
+import type { ICommandEffectQueue } from './command-effect-queue.js';
+
+export function useSlashRouting(
+  interactiveSession: IInteractiveSession,
+  registry: CommandRegistry,
+  manager: TuiStateManager,
+  commandEffectQueue: ICommandEffectQueue,
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void,
+): (input: string) => Promise<void> {
+  return useCallback(
+    async (input: string) => {
+      if (!input.startsWith('/')) {
+        await interactiveSession.submit(input);
+        manager.setPendingPrompt(interactiveSession.getPendingPrompt());
+        return;
+      }
+
+      const parts = input.slice(1).split(/\s+/);
+      const cmd = parts[0]?.toLowerCase() ?? '';
+      const args = parts.slice(1).join(' ');
+
+      // Try system command first
+      const result = await interactiveSession.executeCommand(cmd, args);
+      if (result) {
+        if (result.effects?.some((effect) => effect.type === 'session-execution-started')) {
+          manager.setPendingPrompt(interactiveSession.getPendingPrompt());
+          return;
+        }
+        applySystemCommandResult(
+          result,
+          interactiveSession,
+          registry,
+          manager,
+          commandEffectQueue,
+          reloadPluginCommandSource,
+        );
+        return;
+      }
+
+      manager.addEntry(
+        messageToHistoryEntry(
+          createSystemMessage(`Unknown command "/${cmd}". Type /help for help.`),
+        ),
+      );
+    },
+    [interactiveSession, registry, manager, commandEffectQueue, reloadPluginCommandSource],
+  );
+}
+
+export function applySystemCommandResult(
+  result: ICommandResult,
+  interactiveSession: IInteractiveSession,
+  registry: CommandRegistry,
+  manager: TuiStateManager,
+  commandEffectQueue: ICommandEffectQueue,
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void,
+): void {
+  const pendingEffects = applyImmediateCommandEffects(
+    result.effects,
+    registry,
+    manager,
+    reloadPluginCommandSource,
+  );
+  manager.addEntry(messageToHistoryEntry(createSystemMessage(result.message)));
+
+  if (result.interaction !== undefined) {
+    commandEffectQueue.enqueueInteraction(result.interaction);
+  }
+  if (pendingEffects.length > 0) {
+    commandEffectQueue.enqueueEffects(pendingEffects);
+  }
+
+  if (interactiveSession.isInitialized) {
+    const ctx = interactiveSession.getContextState();
+    manager.setContextState({
+      percentage: ctx.usedPercentage,
+      usedTokens: ctx.usedTokens,
+      maxTokens: ctx.maxTokens,
+    });
+  }
+}
+
+function applyImmediateCommandEffects(
+  effects: readonly TCommandEffect[] | undefined,
+  registry: CommandRegistry,
+  manager: TuiStateManager,
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void,
+): TCommandEffect[] {
+  if (effects === undefined || effects.length === 0) return [];
+  const pendingEffects: TCommandEffect[] = [];
+  for (const effect of effects) {
+    if (effect.type === 'conversation-history-cleared') {
+      manager.clearHistory();
+      continue;
+    }
+    if (effect.type === 'plugin-registry-reload-requested') {
+      reloadPluginCommandSource?.(registry);
+      continue;
+    }
+    pendingEffects.push(effect);
+  }
+  return pendingEffects;
+}

package/src/tui/hooks/useStatusLineSettings.ts

@@ -0,0 +1,35 @@
+import { useState } from 'react';
+import type { IStatusLineCommandSettings } from '@robota-sdk/agent-framework';
+import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+function readStatusLineSettings(
+  settings: Record<string, TUniversalValue>,
+): IStatusLineCommandSettings {
+  const defaults = { ...DEFAULT_STATUS_LINE_COMMAND_SETTINGS };
+  const raw = settings.statusline;
+  if (!isRecord(raw)) {
+    return defaults;
+  }
+  return {
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : defaults.enabled,
+    gitBranch: typeof raw.gitBranch === 'boolean' ? raw.gitBranch : defaults.gitBranch,
+  };
+}
+
+function isRecord(value: TUniversalValue): value is Record<string, TUniversalValue> {
+  return (
+    value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+export function useStatusLineSettings(): [
+  IStatusLineCommandSettings,
+  (settings: IStatusLineCommandSettings) => void,
+] {
+  const cliAdapter = useTuiCliAdapter();
+  return useState<IStatusLineCommandSettings>(() =>
+    readStatusLineSettings(cliAdapter.readSettings(cliAdapter.getUserSettingsPath())),
+  );
+}

package/src/tui/index.ts

@@ -0,0 +1,3 @@
+export { TuiTransport } from './tui-transport.js';
+export type { ITuiCliAdapter } from './tui-cli-adapter.js';
+export type { IRenderOptions } from './render.js';

package/src/tui/plugin-tui-handlers.ts

@@ -0,0 +1,163 @@
+/**
+ * Screen-specific selection handlers for PluginTUI.
+ * Extracted to keep PluginTUI.tsx under 300 lines.
+ */
+
+import type { IMenuSelectItem } from './MenuSelect.js';
+import type { ICommandPluginAdapter } from '@robota-sdk/agent-framework';
+
+interface IConfirmState {
+  message: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+interface IMenuContext {
+  marketplace?: string;
+  pluginId?: string;
+}
+
+interface INavActions {
+  push: (state: { screen: string; context?: IMenuContext }) => void;
+  pop: () => void;
+  popN: (n: number) => void;
+  notify: (content: string) => void;
+  setConfirm: (state: IConfirmState | undefined) => void;
+  refresh: () => void;
+}
+
+export function handleMainSelect(value: string, nav: Pick<INavActions, 'push'>): void {
+  if (value === 'marketplace') {
+    nav.push({ screen: 'marketplace-list' });
+  } else if (value === 'installed') {
+    nav.push({ screen: 'installed-list' });
+  }
+}
+
+export function handleMarketplaceListSelect(value: string, nav: Pick<INavActions, 'push'>): void {
+  if (value === '__add__') {
+    nav.push({ screen: 'marketplace-add' });
+  } else {
+    nav.push({ screen: 'marketplace-action', context: { marketplace: value } });
+  }
+}
+
+export function handleMarketplaceActionSelect(
+  value: string,
+  marketplace: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'push' | 'pop' | 'popN' | 'notify' | 'setConfirm'>,
+): void {
+  if (value === 'browse') {
+    nav.push({ screen: 'marketplace-browse', context: { marketplace } });
+  } else if (value === 'update') {
+    callbacks
+      .marketplaceUpdate(marketplace)
+      .then(() => {
+        nav.notify(`Updated marketplace "${marketplace}".`);
+        nav.pop();
+      })
+      .catch((err) => {
+        nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+      });
+  } else if (value === 'remove') {
+    nav.setConfirm({
+      message: `Remove marketplace "${marketplace}" and all its plugins?`,
+      onConfirm: () => {
+        nav.setConfirm(undefined);
+        callbacks
+          .marketplaceRemove(marketplace)
+          .then(() => {
+            nav.notify(`Removed marketplace "${marketplace}".`);
+            nav.popN(2);
+          })
+          .catch((err) => {
+            nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+          });
+      },
+      onCancel: () => nav.setConfirm(undefined),
+    });
+  }
+}
+
+export function handleMarketplaceBrowseSelect(
+  value: string,
+  marketplace: string,
+  items: IMenuSelectItem[],
+  nav: Pick<INavActions, 'push'>,
+): void {
+  const fullId = `${value}@${marketplace}`;
+  const item = items.find((i) => i.value === value);
+  if (item?.hint === 'installed') {
+    nav.push({ screen: 'installed-action', context: { pluginId: fullId } });
+  } else {
+    nav.push({ screen: 'marketplace-install-scope', context: { marketplace, pluginId: fullId } });
+  }
+}
+
+export function handleInstallScopeSelect(
+  value: string,
+  pluginId: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'popN' | 'notify'>,
+): void {
+  const scope = value as 'user' | 'project';
+  callbacks
+    .install(pluginId, scope)
+    .then(() => {
+      nav.notify(`Installed plugin "${pluginId}" (${scope} scope).`);
+      nav.popN(2);
+    })
+    .catch((err) => {
+      nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    });
+}
+
+export function handleInstalledListSelect(
+  value: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'notify' | 'setConfirm' | 'refresh'>,
+): void {
+  nav.setConfirm({
+    message: `Uninstall plugin "${value}"?`,
+    onConfirm: () => {
+      nav.setConfirm(undefined);
+      callbacks
+        .uninstall(value)
+        .then(() => {
+          nav.notify(`Uninstalled plugin "${value}".`);
+          nav.refresh();
+        })
+        .catch((err) => {
+          nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    },
+    onCancel: () => nav.setConfirm(undefined),
+  });
+}
+
+export function handleInstalledActionSelect(
+  value: string,
+  pluginId: string,
+  callbacks: ICommandPluginAdapter,
+  nav: Pick<INavActions, 'popN' | 'notify' | 'setConfirm'>,
+): void {
+  if (value === 'uninstall') {
+    nav.setConfirm({
+      message: `Uninstall plugin "${pluginId}"?`,
+      onConfirm: () => {
+        nav.setConfirm(undefined);
+        callbacks
+          .uninstall(pluginId)
+          .then(() => {
+            nav.notify(`Uninstalled plugin "${pluginId}".`);
+            nav.popN(2);
+          })
+          .catch((err) => {
+            nav.notify(`Error: ${err instanceof Error ? err.message : String(err)}`);
+          });
+      },
+      onCancel: () => nav.setConfirm(undefined),
+    });
+  }
+}

package/src/tui/render-markdown.ts

@@ -0,0 +1,129 @@
+import { marked } from 'marked';
+import type { Renderer } from 'marked';
+// @ts-expect-error — marked-terminal has no type declarations
+import TerminalRenderer from 'marked-terminal';
+
+const ANSI_LIGHT_RED = '\u001b[38;5;210m';
+const ANSI_LIGHT_GREEN = '\u001b[38;5;120m';
+const ANSI_CYAN = '\u001b[36m';
+const ANSI_DIM = '\u001b[2m';
+const ANSI_DARK_RED_BACKGROUND = '\u001b[48;5;52m';
+const ANSI_DARK_GREEN_BACKGROUND = '\u001b[48;5;22m';
+const ANSI_RESET = '\u001b[0m';
+const CODE_BLOCK_INDENT = '    ';
+const ZERO_COLOR = '0';
+
+interface IRenderMarkdownOptions {
+  color?: boolean;
+  codeBlockWidth?: number;
+}
+
+interface ITerminalRendererOptions {
+  code?: (text: string) => string;
+}
+
+interface IHighlightOptions {
+  ignoreIllegals?: boolean;
+}
+
+type TTerminalRendererConstructor = new (
+  options?: ITerminalRendererOptions,
+  highlightOptions?: IHighlightOptions,
+) => Renderer;
+
+const TerminalRendererConstructor = TerminalRenderer as TTerminalRendererConstructor;
+
+function shouldUseColor(option: boolean | undefined): boolean {
+  if (option !== undefined) {
+    return option;
+  }
+  if (process.env.NO_COLOR || process.env.FORCE_COLOR === ZERO_COLOR) {
+    return false;
+  }
+  if (process.env.FORCE_COLOR) {
+    return true;
+  }
+  return Boolean(process.stdout.isTTY);
+}
+
+function isDiffLanguage(language: string | undefined): boolean {
+  return language?.trim().toLowerCase() === 'diff';
+}
+
+function styleAddedOrRemovedDiffRow(line: string, rowWidth: number, color: boolean): string {
+  const row = `${CODE_BLOCK_INDENT}${line}`.padEnd(rowWidth);
+  if (!color) {
+    return row.trimEnd();
+  }
+  if (line.startsWith('+')) {
+    return `${ANSI_DARK_GREEN_BACKGROUND}${ANSI_LIGHT_GREEN}${row}${ANSI_RESET}`;
+  }
+  if (line.startsWith('-')) {
+    return `${ANSI_DARK_RED_BACKGROUND}${ANSI_LIGHT_RED}${row}${ANSI_RESET}`;
+  }
+  return row.trimEnd();
+}
+
+function colorizeDiffLine(line: string, color: boolean, rowWidth: number): string {
+  if (line.startsWith('+') || line.startsWith('-')) {
+    return styleAddedOrRemovedDiffRow(line, rowWidth, color);
+  }
+  const row = `${CODE_BLOCK_INDENT}${line}`;
+  if (!color) {
+    return row;
+  }
+  if (line.startsWith('@@')) {
+    return `${ANSI_CYAN}${row}${ANSI_RESET}`;
+  }
+  if (line.startsWith('diff ') || line.startsWith('index ')) {
+    return `${ANSI_DIM}${row}${ANSI_RESET}`;
+  }
+  return row;
+}
+
+function resolveDiffRowWidth(lines: readonly string[], requestedWidth: number | undefined): number {
+  const minimumWidth = lines.reduce(
+    (maxWidth, line) => Math.max(maxWidth, CODE_BLOCK_INDENT.length + line.length),
+    0,
+  );
+  if (requestedWidth === undefined) {
+    return minimumWidth;
+  }
+  return Math.max(minimumWidth, requestedWidth);
+}
+
+function renderDiffCodeBlock(
+  code: string,
+  color: boolean,
+  codeBlockWidth: number | undefined,
+): string {
+  const lines = code.split('\n');
+  const rowWidth = resolveDiffRowWidth(lines, codeBlockWidth);
+  const body = lines.map((line) => colorizeDiffLine(line, color, rowWidth)).join('\n');
+  return `${body}\n\n`;
+}
+
+function createTerminalRenderer(color: boolean, codeBlockWidth: number | undefined): Renderer {
+  const renderer = new TerminalRendererConstructor(undefined, { ignoreIllegals: true });
+  const renderCode = renderer.code.bind(renderer);
+
+  renderer.code = (code: string, language: string | undefined, escaped: boolean): string => {
+    if (isDiffLanguage(language)) {
+      return renderDiffCodeBlock(code, color, codeBlockWidth);
+    }
+    return renderCode(code, language, escaped);
+  };
+
+  return renderer;
+}
+
+/**
+ * Render markdown to a terminal-formatted string with colors, bold, etc.
+ * Returns the rendered string (may include ANSI escape codes).
+ */
+export function renderMarkdown(md: string, options: IRenderMarkdownOptions = {}): string {
+  const result = marked.parse(md, {
+    renderer: createTerminalRenderer(shouldUseColor(options.color), options.codeBlockWidth),
+  });
+  return typeof result === 'string' ? result.trimEnd() : md;
+}

package/src/tui/render.tsx

@@ -0,0 +1,60 @@
+/**
+ * Ink render entry point.
+ */
+
+import React from 'react';
+import { render } from 'ink';
+import App from './App.js';
+import type { IAIProvider } from '@robota-sdk/agent-core';
+import type { TPermissionMode } from '@robota-sdk/agent-core';
+import type {
+  IBackgroundTaskRunner,
+  ICommandHostAdapters,
+  ICommandModule,
+  IInteractiveSession,
+  IInteractiveSessionStore,
+  TSubagentRunnerFactory,
+  TShellExecFn,
+  CommandRegistry,
+} from '@robota-sdk/agent-framework';
+import type { ITransportRegistryView } from '@robota-sdk/agent-interface-transport';
+import type { ITuiCliAdapter } from './tui-cli-adapter.js';
+
+export interface IRenderOptions {
+  cwd: string;
+  provider: IAIProvider;
+  providerOverride?: string | undefined;
+  providerType?: string | undefined;
+  modelId?: string;
+  language?: string;
+  permissionMode?: TPermissionMode;
+  maxTurns?: number;
+  version?: string;
+  sessionStore?: IInteractiveSessionStore;
+  resumeSessionId?: string;
+  showSessionPickerOnStart?: boolean;
+  forkSession?: boolean;
+  sessionName?: string;
+  backgroundTaskRunners?: IBackgroundTaskRunner[];
+  subagentRunnerFactory?: TSubagentRunnerFactory;
+  commandModules?: readonly ICommandModule[];
+  commandHostAdapters?: ICommandHostAdapters;
+  shellExec?: TShellExecFn;
+  startupUpdateNotice?: Promise<string | undefined>;
+  transportRegistry?: ITransportRegistryView<IInteractiveSession>;
+  cliAdapter: ITuiCliAdapter;
+  reloadPluginCommandSource?: (registry: CommandRegistry) => void;
+  agentName?: string;
+}
+
+export async function renderApp(options: IRenderOptions): Promise<void> {
+  process.on('unhandledRejection', (reason) => {
+    process.stderr.write(`\n[UNHANDLED REJECTION] ${reason}\n`);
+    if (reason instanceof Error) {
+      process.stderr.write(`${reason.stack}\n`);
+    }
+  });
+
+  const instance = render(<App {...options} />, { exitOnCtrlC: false });
+  await instance.waitUntilExit();
+}

package/src/tui/status-activity.ts

@@ -0,0 +1,63 @@
+export type TStatusActivityKind = 'tools' | 'thinking' | 'background' | 'queued' | 'idle';
+
+export interface IStatusActivityInput {
+  isThinking: boolean;
+  activeToolCount: number;
+  activeBackgroundTaskCount: number;
+  hasPendingPrompt: boolean;
+}
+
+export interface IStatusActivity {
+  kind: TStatusActivityKind;
+  label: string;
+  color: string;
+  segments: string[];
+  text: string;
+}
+
+const NO_ACTIVE_ITEMS = 0;
+
+export function formatStatusActivity(input: IStatusActivityInput): IStatusActivity {
+  const base = getPrimaryActivity(input);
+  const segments = input.hasPendingPrompt && base.kind !== 'queued' ? ['queued'] : [];
+  const text = [base.label, ...segments].join(' · ');
+  return { ...base, segments, text };
+}
+
+function getPrimaryActivity(
+  input: IStatusActivityInput,
+): Omit<IStatusActivity, 'segments' | 'text'> {
+  if (input.activeToolCount > NO_ACTIVE_ITEMS) {
+    return {
+      kind: 'tools',
+      label: `Tools x${input.activeToolCount}`,
+      color: 'cyan',
+    };
+  }
+  if (input.isThinking) {
+    return {
+      kind: 'thinking',
+      label: 'Thinking',
+      color: 'yellow',
+    };
+  }
+  if (input.activeBackgroundTaskCount > NO_ACTIVE_ITEMS) {
+    return {
+      kind: 'background',
+      label: `Background x${input.activeBackgroundTaskCount}`,
+      color: 'cyan',
+    };
+  }
+  if (input.hasPendingPrompt) {
+    return {
+      kind: 'queued',
+      label: 'Queued',
+      color: 'yellow',
+    };
+  }
+  return {
+    kind: 'idle',
+    label: 'Idle',
+    color: 'gray',
+  };
+}

package/src/tui/tui-cli-adapter-context.tsx

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react';
+import type { ITuiCliAdapter } from './tui-cli-adapter.js';
+
+const TuiCliAdapterContext = createContext<ITuiCliAdapter | null>(null);
+
+export const TuiCliAdapterProvider = TuiCliAdapterContext.Provider;
+
+export function useTuiCliAdapter(): ITuiCliAdapter {
+  const adapter = useContext(TuiCliAdapterContext);
+  if (!adapter) throw new Error('TuiCliAdapterContext not provided');
+  return adapter;
+}

package/src/tui/tui-cli-adapter.ts

@@ -0,0 +1,25 @@
+import type {
+  TStatusLineCommandSettingsPatch,
+  IStatusLineCommandSettings,
+  CommandRegistry,
+} from '@robota-sdk/agent-framework';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+export interface ITuiCliAdapter {
+  getUserSettingsPath(): string;
+  readSettings(path: string): Record<string, TUniversalValue>;
+  writeSettings(path: string, settings: Record<string, TUniversalValue>): void;
+  deleteSettings(path: string): boolean;
+  applyStatusLineSettings(
+    path: string,
+    patch: TStatusLineCommandSettingsPatch,
+  ): IStatusLineCommandSettings;
+  reloadPluginCommandSource(registry: CommandRegistry): void;
+  applyActiveModelChange(
+    cwd: string,
+    modelId: string,
+    options?: { providerOverride?: string },
+  ): { applied: boolean };
+  getGitBranch(cwd: string): string | undefined;
+  getProviderDisplayName(type: string): string;
+}