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

package/src/tui/__tests__/text-prompt-flow.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyTextPromptInput,
+  createTextPromptFlowState,
+  getTextPromptInputAction,
+  type ITextPromptFlowState,
+} from '../flows/text-prompt-flow.js';
+
+describe('text prompt flow', () => {
+  it('Given typed text When submit is applied Then it emits trimmed submit value', () => {
+    const typed = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'insert', value: '  hello  ' },
+      { allowEmpty: false },
+    ).state;
+
+    const result = applyTextPromptInput(typed, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'submit', value: 'hello' });
+    expect(result.state.resolved).toBe(true);
+  });
+
+  it('Given empty required text When submit is applied Then validation error stays in state', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: false, validate: (value) => (value.length === 0 ? 'Required' : undefined) },
+    );
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state.error).toBe('Required');
+    expect(result.state.resolved).toBe(false);
+  });
+
+  it('Given defaultable empty text When submit is applied Then empty submit is allowed', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'submit', value: '' });
+  });
+
+  it('Given text with an error When delete or insert is applied Then the error is cleared', () => {
+    const state: ITextPromptFlowState = { value: 'ab', error: 'Invalid', resolved: false };
+
+    const deleted = applyTextPromptInput(state, { type: 'delete' }, { allowEmpty: false });
+    const inserted = applyTextPromptInput(
+      state,
+      { type: 'insert', value: 'c' },
+      { allowEmpty: false },
+    );
+
+    expect(deleted.state).toMatchObject({ value: 'a', error: undefined });
+    expect(inserted.state).toMatchObject({ value: 'abc', error: undefined });
+  });
+
+  it('Given prompt is already resolved When input is applied Then no second effect is emitted', () => {
+    const state: ITextPromptFlowState = { value: 'done', resolved: true };
+
+    const result = applyTextPromptInput(state, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state).toBe(state);
+  });
+
+  it('Given raw Ink key info When mapped Then terminal details become prompt actions', () => {
+    expect(getTextPromptInputAction('', { escape: true })).toEqual({ type: 'cancel' });
+    expect(getTextPromptInputAction('', { return: true })).toEqual({ type: 'submit' });
+    expect(getTextPromptInputAction('', { backspace: true })).toEqual({ type: 'delete' });
+    expect(getTextPromptInputAction('x', { ctrl: false, meta: false })).toEqual({
+      type: 'insert',
+      value: 'x',
+    });
+  });
+});

package/src/tui/__tests__/tui-state-manager.test.ts

@@ -0,0 +1,401 @@
+/**
+ * Unit tests for TuiStateManager — pure TypeScript, no React.
+ * Tests event → state transitions that must survive any refactoring.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { TuiStateManager } from '../tui-state-manager.js';
+import type { IToolState, IExecutionResult } from '@robota-sdk/agent-framework';
+
+function makeResult(overrides?: Partial<IExecutionResult>): IExecutionResult {
+  return {
+    response: 'test response',
+    history: [],
+    toolSummaries: [],
+    contextState: {
+      usedPercentage: 10,
+      remainingPercentage: 90,
+      usedTokens: 1000,
+      maxTokens: 200000,
+    },
+    ...overrides,
+  };
+}
+
+describe('TuiStateManager', () => {
+  // ── Streaming text ────────────────────────────────────────────
+
+  it('accumulates streaming text on text_delta', () => {
+    const mgr = new TuiStateManager();
+    mgr.onTextDelta('Hello');
+    mgr.onTextDelta(' world');
+    expect(mgr.streamingText).toBe('Hello world');
+  });
+
+  it('clears streaming text on thinking=true', () => {
+    const mgr = new TuiStateManager();
+    mgr.onTextDelta('old text');
+    mgr.onThinking(true);
+    expect(mgr.streamingText).toBe('');
+  });
+
+  it('clears streaming text on complete', () => {
+    const mgr = new TuiStateManager();
+    mgr.onTextDelta('streaming');
+    mgr.onComplete(makeResult());
+    expect(mgr.streamingText).toBe('');
+  });
+
+  it('clears streaming text on interrupted', () => {
+    const mgr = new TuiStateManager();
+    mgr.onTextDelta('partial');
+    mgr.onInterrupted();
+    expect(mgr.streamingText).toBe('');
+  });
+
+  // ── Tool state ────────────────────────────────────────────────
+
+  it('adds tool on tool_start', () => {
+    const mgr = new TuiStateManager();
+    const tool: IToolState = { toolName: 'Read', firstArg: 'file.ts', isRunning: true };
+    mgr.onToolStart(tool);
+    expect(mgr.activeTools).toHaveLength(1);
+    expect(mgr.activeTools[0]!.toolName).toBe('Read');
+  });
+
+  it('updates tool on tool_end', () => {
+    const mgr = new TuiStateManager();
+    mgr.onToolStart({ toolName: 'Read', firstArg: 'file.ts', isRunning: true });
+    mgr.onToolEnd({ toolName: 'Read', firstArg: 'file.ts', isRunning: false, result: 'success' });
+    expect(mgr.activeTools[0]!.isRunning).toBe(false);
+    expect(mgr.activeTools[0]!.result).toBe('success');
+  });
+
+  it('clears tools on thinking=true (next execution start)', () => {
+    const mgr = new TuiStateManager();
+    mgr.onToolStart({ toolName: 'Read', firstArg: '', isRunning: true });
+    mgr.onThinking(true);
+    expect(mgr.activeTools).toEqual([]);
+  });
+
+  it('clears tools on complete (tool summary now in messages)', () => {
+    const mgr = new TuiStateManager();
+    mgr.onToolStart({ toolName: 'Read', firstArg: '', isRunning: true });
+    mgr.onComplete(makeResult());
+    expect(mgr.activeTools).toEqual([]);
+  });
+
+  it('clears tools on interrupted (tool summary now in messages)', () => {
+    const mgr = new TuiStateManager();
+    mgr.onToolStart({ toolName: 'Read', firstArg: '', isRunning: true });
+    mgr.onInterrupted();
+    expect(mgr.activeTools).toEqual([]);
+  });
+
+  it('clears rendered history, streaming text, and active tools on explicit history clear', () => {
+    const mgr = new TuiStateManager();
+    mgr.addEntry({
+      id: 'old',
+      timestamp: new Date('2026-05-03T00:00:00.000Z'),
+      category: 'chat',
+      type: 'user',
+      data: { role: 'user', content: 'old message' },
+    });
+    mgr.onTextDelta('partial');
+    mgr.onToolStart({ toolName: 'Read', firstArg: 'file.ts', isRunning: true });
+
+    mgr.clearHistory();
+
+    expect(mgr.history).toEqual([]);
+    expect(mgr.streamingText).toBe('');
+    expect(mgr.activeTools).toEqual([]);
+  });
+
+  // ── Thinking state ────────────────────────────────────────────
+
+  it('sets isThinking on thinking event', () => {
+    const mgr = new TuiStateManager();
+    mgr.onThinking(true);
+    expect(mgr.isThinking).toBe(true);
+    mgr.onThinking(false);
+    expect(mgr.isThinking).toBe(false);
+  });
+
+  it('clears isAborting on thinking=false', () => {
+    const mgr = new TuiStateManager();
+    mgr.setAborting(true);
+    expect(mgr.isAborting).toBe(true);
+    mgr.onThinking(false);
+    expect(mgr.isAborting).toBe(false);
+  });
+
+  // ── Context state ─────────────────────────────────────────────
+
+  it('updates context on complete', () => {
+    const mgr = new TuiStateManager();
+    mgr.onComplete(
+      makeResult({
+        contextState: {
+          usedPercentage: 50,
+          remainingPercentage: 50,
+          usedTokens: 5000,
+          maxTokens: 10000,
+        },
+      }),
+    );
+    expect(mgr.contextState.percentage).toBe(50);
+    expect(mgr.contextState.usedTokens).toBe(5000);
+  });
+
+  // ── Messages ──────────────────────────────────────────────────
+
+  it('addMessage appends to messages', () => {
+    const mgr = new TuiStateManager();
+    mgr.addEntry({ role: 'user', content: 'hello' } as never);
+    mgr.addEntry({ role: 'assistant', content: 'world' } as never);
+    expect(mgr.history).toHaveLength(2);
+  });
+
+  it('addEntry windows to MAX_RENDERED_MESSAGES', () => {
+    const mgr = new TuiStateManager();
+    for (let i = 0; i < 110; i++) {
+      mgr.addEntry({
+        id: `${i}`,
+        timestamp: new Date(),
+        category: 'chat',
+        type: 'user',
+        data: { content: `msg ${i}` },
+      } as never);
+    }
+    expect(mgr.history).toHaveLength(100);
+  });
+
+  it('syncMessages replaces all messages', () => {
+    const mgr = new TuiStateManager();
+    mgr.addEntry({ role: 'user', content: 'old' } as never);
+    mgr.syncHistory([
+      { role: 'user', content: 'new1' } as never,
+      { role: 'assistant', content: 'new2' } as never,
+    ]);
+    expect(mgr.history).toHaveLength(2);
+    expect((mgr.history[0]! as unknown as { content: string }).content).toBe('new1');
+  });
+
+  // ── onChange notification ──────────────────────────────────────
+
+  it('calls onChange on every non-debounced state change', () => {
+    const mgr = new TuiStateManager();
+    const onChange = vi.fn();
+    mgr.onChange = onChange;
+
+    mgr.onTextDelta('hi'); // debounced — does NOT call onChange immediately
+    mgr.onToolStart({ toolName: 'Read', firstArg: '', isRunning: true });
+    mgr.onThinking(true); // flushes debounce timer
+    mgr.addEntry({ role: 'user', content: 'test' } as never);
+    mgr.setAborting(true);
+    mgr.setPendingPrompt('queued');
+    mgr.setContextState({ percentage: 50, usedTokens: 5000, maxTokens: 10000 });
+
+    expect(onChange).toHaveBeenCalledTimes(6);
+  });
+
+  it('onTextDelta debounces notify calls', async () => {
+    const mgr = new TuiStateManager();
+    const onChange = vi.fn();
+    mgr.onChange = onChange;
+
+    mgr.onTextDelta('a');
+    mgr.onTextDelta('b');
+    mgr.onTextDelta('c');
+
+    expect(onChange).toHaveBeenCalledTimes(0);
+    expect(mgr.streamingText).toBe('abc');
+
+    await new Promise((r) => setTimeout(r, 400));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not crash when onChange is null', () => {
+    const mgr = new TuiStateManager();
+    expect(() => mgr.onTextDelta('hi')).not.toThrow();
+  });
+
+  it('stores SDK execution workspace snapshots and preserves selected entry across updates', () => {
+    const mgr = new TuiStateManager();
+    const snapshot = {
+      sessionId: 'session_1',
+      selectedEntryId: 'main:session_1',
+      updatedAt: '2026-05-09T00:00:00.000Z',
+      entries: [
+        {
+          id: 'main:session_1',
+          sourceId: 'session_1',
+          kind: 'main_thread',
+          origin: { kind: 'user_prompt', sessionId: 'session_1' },
+          status: 'idle',
+          title: 'Main thread',
+          unread: false,
+          attention: 'none',
+          visibility: 'default',
+          updatedAt: '2026-05-09T00:00:00.000Z',
+          controls: ['select'],
+        },
+        {
+          id: 'task:agent_1',
+          sourceId: 'agent_1',
+          kind: 'background_task',
+          origin: { kind: 'slash_command', sessionId: 'session_1' },
+          taskKind: 'agent',
+          status: 'running',
+          title: 'Explore',
+          unread: false,
+          attention: 'none',
+          visibility: 'default',
+          updatedAt: '2026-05-09T00:00:01.000Z',
+          controls: ['select', 'cancel'],
+        },
+      ],
+    } as const;
+
+    mgr.syncExecutionWorkspaceSnapshot(snapshot);
+    mgr.selectExecutionWorkspaceEntry('task:agent_1');
+    mgr.syncExecutionWorkspaceSnapshot({ ...snapshot, updatedAt: '2026-05-09T00:00:02.000Z' });
+
+    expect(mgr.selectedExecutionEntryId).toBe('task:agent_1');
+    expect(mgr.executionWorkspaceSnapshot?.selectedEntryId).toBe('task:agent_1');
+  });
+
+  // ── Display order: Tool → Robota ──────────────────────────────
+
+  it('streaming state is cleared on complete (tools moved to messages)', () => {
+    const mgr = new TuiStateManager();
+    mgr.onThinking(true);
+    mgr.onTextDelta('streaming response');
+    mgr.onToolStart({ toolName: 'Read', firstArg: 'f.ts', isRunning: true });
+    mgr.onToolEnd({ toolName: 'Read', firstArg: 'f.ts', isRunning: false, result: 'success' });
+
+    expect(mgr.streamingText).toBe('streaming response');
+    expect(mgr.activeTools).toHaveLength(1);
+
+    mgr.onComplete(makeResult());
+
+    // After complete: streaming cleared, tools cleared
+    expect(mgr.streamingText).toBe('');
+    expect(mgr.activeTools).toEqual([]);
+    // Tool info is now in InteractiveSession's messages (not managed here)
+  });
+
+  it('streaming state is cleared on abort (tools moved to messages)', () => {
+    const mgr = new TuiStateManager();
+    mgr.onThinking(true);
+    mgr.onTextDelta('partial');
+    mgr.onToolStart({ toolName: 'Bash', firstArg: 'ls', isRunning: true });
+
+    mgr.onInterrupted();
+
+    expect(mgr.streamingText).toBe('');
+    expect(mgr.activeTools).toEqual([]);
+  });
+
+  // ── Full lifecycle: streaming → completion message order ──────
+
+  it('during streaming: tools and text visible in StreamingIndicator state', () => {
+    const mgr = new TuiStateManager();
+
+    // Execution starts
+    mgr.onThinking(true);
+
+    // Tools arrive
+    mgr.onToolStart({ toolName: 'Read', firstArg: 'file.ts', isRunning: true });
+    mgr.onToolEnd({ toolName: 'Read', firstArg: 'file.ts', isRunning: false, result: 'success' });
+    mgr.onToolStart({ toolName: 'Edit', firstArg: 'file.ts', isRunning: true });
+
+    // Streaming text arrives
+    mgr.onTextDelta('Here is the ');
+    mgr.onTextDelta('result');
+
+    // During streaming: both active
+    expect(mgr.activeTools).toHaveLength(2);
+    expect(mgr.streamingText).toBe('Here is the result');
+    expect(mgr.isThinking).toBe(true);
+  });
+
+  it('after completion: streaming cleared, messages synced from session', () => {
+    const mgr = new TuiStateManager();
+
+    mgr.onThinking(true);
+    mgr.onToolStart({ toolName: 'Read', firstArg: 'f.ts', isRunning: true });
+    mgr.onToolEnd({ toolName: 'Read', firstArg: 'f.ts', isRunning: false, result: 'success' });
+    mgr.onTextDelta('response text');
+
+    // Complete event fires, then thinking ends
+    mgr.onComplete(makeResult());
+    mgr.onThinking(false);
+
+    // StreamingIndicator state: cleared
+    expect(mgr.streamingText).toBe('');
+    expect(mgr.activeTools).toEqual([]);
+    expect(mgr.isThinking).toBe(false);
+
+    // Simulate InteractiveSession history entries being synced
+    mgr.syncHistory([
+      { id: '1', timestamp: new Date(), category: 'chat', type: 'user' } as never,
+      { id: '2', timestamp: new Date(), category: 'event', type: 'tool-summary' } as never,
+      { id: '3', timestamp: new Date(), category: 'chat', type: 'assistant' } as never,
+    ]);
+
+    // MessageList now has correct order: user → tool-summary → assistant
+    expect(mgr.history).toHaveLength(3);
+    expect(mgr.history[0]!.type).toBe('user');
+    expect(mgr.history[1]!.type).toBe('tool-summary');
+    expect(mgr.history[2]!.type).toBe('assistant');
+  });
+
+  it('after abort: streaming cleared, messages synced with tool → robota → system', () => {
+    const mgr = new TuiStateManager();
+
+    mgr.onThinking(true);
+    mgr.onToolStart({ toolName: 'Bash', firstArg: 'ls', isRunning: true });
+    mgr.onTextDelta('partial answer');
+
+    mgr.onInterrupted();
+
+    expect(mgr.streamingText).toBe('');
+    expect(mgr.activeTools).toEqual([]);
+
+    // Simulate InteractiveSession history entries synced after abort
+    mgr.syncHistory([
+      { id: '1', timestamp: new Date(), category: 'chat', type: 'user' } as never,
+      { id: '2', timestamp: new Date(), category: 'event', type: 'tool-summary' } as never,
+      { id: '3', timestamp: new Date(), category: 'chat', type: 'assistant' } as never,
+      { id: '4', timestamp: new Date(), category: 'chat', type: 'system' } as never,
+    ]);
+
+    // Order: user → tool-summary → assistant → system
+    expect(mgr.history).toHaveLength(4);
+    expect(mgr.history[0]!.type).toBe('user');
+    expect(mgr.history[1]!.type).toBe('tool-summary');
+    expect(mgr.history[2]!.type).toBe('assistant');
+    expect(mgr.history[3]!.type).toBe('system');
+  });
+
+  it('next execution clears previous tools from StreamingIndicator', () => {
+    const mgr = new TuiStateManager();
+
+    // First execution
+    mgr.onThinking(true);
+    mgr.onToolStart({ toolName: 'Read', firstArg: '', isRunning: true });
+    mgr.onComplete(makeResult());
+    expect(mgr.activeTools).toEqual([]);
+
+    // Second execution starts
+    mgr.onThinking(true);
+    // Previous tools should not reappear
+    expect(mgr.activeTools).toEqual([]);
+
+    // New tools for second execution
+    mgr.onToolStart({ toolName: 'Write', firstArg: 'new.ts', isRunning: true });
+    expect(mgr.activeTools).toHaveLength(1);
+    expect(mgr.activeTools[0]!.toolName).toBe('Write');
+  });
+});

package/src/tui/background-task-row-format.ts

@@ -0,0 +1,52 @@
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-framework';
+import { formatExecutionWorkspaceEntryRow } from './execution-workspace-view-model.js';
+
+export interface IBackgroundTaskRow {
+  connector: '├' | '└';
+  marker: '□' | '■';
+  color: string;
+  label: string;
+  segments: string[];
+  preview?: string;
+  accessibleText: string;
+}
+
+export interface IBackgroundTaskRowOptions {
+  isLast?: boolean;
+}
+
+export function formatBackgroundTaskRow(
+  entry: IExecutionWorkspaceEntry,
+  options: IBackgroundTaskRowOptions = {},
+): IBackgroundTaskRow {
+  const row = formatExecutionWorkspaceEntryRow(entry);
+  const marker = isActiveEntry(entry) ? '□' : '■';
+  const segments = [row.statusLabel, row.subtitle].filter(
+    (segment): segment is string => typeof segment === 'string' && segment.length > 0,
+  );
+  return {
+    connector: options.isLast === false ? '├' : '└',
+    marker,
+    color: row.color,
+    label: row.title,
+    segments,
+    preview: row.preview,
+    accessibleText: [
+      `${options.isLast === false ? '├' : '└'} ${marker} ${row.title}`,
+      ...segments,
+      row.preview,
+    ]
+      .filter((part): part is string => typeof part === 'string' && part.length > 0)
+      .join(' · '),
+  };
+}
+
+function isActiveEntry(entry: IExecutionWorkspaceEntry): boolean {
+  return (
+    entry.status === 'active' ||
+    entry.status === 'queued' ||
+    entry.status === 'running' ||
+    entry.status === 'waiting_permission' ||
+    entry.status === 'sleeping'
+  );
+}

package/src/tui/command-output-summary.ts

@@ -0,0 +1,122 @@
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+
+const MAX_PREVIEW_LINES = 4;
+const SUCCESS_EXIT_CODE = 0;
+const COMMAND_TOOL_NAMES = new Set(['Bash', 'BackgroundProcess']);
+
+export interface ICommandOutputInput {
+  toolName: string;
+  firstArg?: string;
+  isRunning?: boolean;
+  result?: string;
+  toolResultData?: string;
+}
+
+export interface ICommandOutputSummary {
+  status: 'success' | 'error';
+  statusLabel: string;
+  previewLines: string[];
+  omittedLineCount: number;
+  transcriptHint?: string;
+}
+
+export function formatCommandOutputSummary(
+  tool: ICommandOutputInput,
+): ICommandOutputSummary | undefined {
+  if (!COMMAND_TOOL_NAMES.has(tool.toolName) || !tool.toolResultData) return undefined;
+
+  const parsed = parseToolResultData(tool.toolResultData);
+  const exitCode = getNumberValue(parsed, 'exitCode');
+  const successValue = getBooleanValue(parsed, 'success');
+  const output = buildOutputText(tool.toolResultData, parsed);
+  const lines = trimTrailingBlankLines(splitOutputLines(output));
+  const previewLines = lines.slice(0, MAX_PREVIEW_LINES);
+  const omittedLineCount = Math.max(0, lines.length - previewLines.length);
+  const isFailed =
+    tool.result === 'error' ||
+    successValue === false ||
+    (exitCode !== undefined && exitCode !== SUCCESS_EXIT_CODE);
+
+  return {
+    status: isFailed ? 'error' : 'success',
+    statusLabel: formatStatusLabel(isFailed, exitCode),
+    previewLines,
+    omittedLineCount,
+    transcriptHint:
+      omittedLineCount > 0
+        ? `... +${omittedLineCount} lines (full output in session transcript)`
+        : undefined,
+  };
+}
+
+function parseToolResultData(value: string): TUniversalValue {
+  try {
+    return JSON.parse(value) as TUniversalValue;
+  } catch {
+    return value;
+  }
+}
+
+function buildOutputText(raw: string, parsed: TUniversalValue): string {
+  if (!isUniversalObject(parsed)) return raw;
+
+  const output = getStringValue(parsed, 'output');
+  if (output !== undefined) return output;
+
+  const stdout = getStringValue(parsed, 'stdout');
+  const stderr = getStringValue(parsed, 'stderr');
+  const error = getStringValue(parsed, 'error');
+  const lines: string[] = [];
+  if (stdout) lines.push(stdout);
+  if (stderr) lines.push(prefixLines(stderr, '[stderr] '));
+  if (!stdout && !stderr && error) lines.push(error);
+  return lines.join('\n');
+}
+
+function formatStatusLabel(isFailed: boolean, exitCode: number | undefined): string {
+  if (exitCode !== undefined && exitCode !== SUCCESS_EXIT_CODE) return `exit ${exitCode}`;
+  return isFailed ? 'error' : 'ok';
+}
+
+function splitOutputLines(output: string): string[] {
+  if (!output) return [];
+  return output.replace(/\r\n/g, '\n').split('\n');
+}
+
+function trimTrailingBlankLines(lines: string[]): string[] {
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim().length === 0) {
+    end -= 1;
+  }
+  return lines.slice(0, end);
+}
+
+function prefixLines(value: string, prefix: string): string {
+  return splitOutputLines(value)
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function isUniversalObject(value: TUniversalValue): value is Record<string, TUniversalValue> {
+  return (
+    typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+function getStringValue(source: TUniversalValue, key: string): string | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function getNumberValue(source: TUniversalValue, key: string): number | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function getBooleanValue(source: TUniversalValue, key: string): boolean | undefined {
+  if (!isUniversalObject(source)) return undefined;
+  const value = source[key];
+  return typeof value === 'boolean' ? value : undefined;
+}