feat(cli): add timeout display to terminal commands

- Show timeout value next to command (e.g., "60s timeout", "2m timeout", "1h timeout")
- Hide default 30s timeout to reduce visual noise
- Handle edge cases: negative values, NaN, Infinity, floating points
- Extract formatTimeout to shared utility for reusability
- Add comprehensive unit tests for formatting logic

Author: brandonkachen

cli/src/components/terminal-command-display.tsx

@@ -4,6 +4,7 @@ import { useState } from 'react'
 import { Button } from './button'
 import { useTerminalDimensions } from '../hooks/use-terminal-dimensions'
 import { useTheme } from '../hooks/use-theme'
+import { formatTimeout } from '../utils/format-timeout'
 import { getLastNVisualLines } from '../utils/text-layout'
 
 interface TerminalCommandDisplayProps {
@@ -17,19 +18,21 @@ interface TerminalCommandDisplayProps {
   isRunning?: boolean
   /** Working directory where the command was run */
   cwd?: string
+  /** Timeout in seconds for the command */
+  timeoutSeconds?: number
 }
 
 /**
  * Shared component for displaying terminal command with output.
  * Used in both the ghost message (pending bash) and message history.
  */
-
 export const TerminalCommandDisplay = ({
   command,
   output,
   expandable = true,
   maxVisibleLines,
   isRunning = false,
+  timeoutSeconds,
 }: TerminalCommandDisplayProps) => {
   const theme = useTheme()
   const { contentMaxWidth } = useTerminalDimensions()
@@ -40,13 +43,25 @@ export const TerminalCommandDisplay = ({
   const defaultMaxLines = expandable ? 5 : 10
   const maxLines = maxVisibleLines ?? defaultMaxLines
 
+  // Format timeout display - show when provided and not the default (30s)
+  const DEFAULT_TIMEOUT_SECONDS = 30
+  const timeoutLabel =
+    timeoutSeconds !== undefined && timeoutSeconds !== DEFAULT_TIMEOUT_SECONDS
+      ? formatTimeout(timeoutSeconds)
+      : null
+
   // Command header - shared between output and no-output cases
   const commandHeader = (
     <text style={{ wrapMode: 'word' }}>
       <span fg={theme.success}>$ </span>
       <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
         {command}
       </span>
+      {timeoutLabel && (
+        <span fg={theme.muted} attributes={TextAttributes.DIM}>
+          {' '}({timeoutLabel})
+        </span>
+      )}
     </text>
   )
 

cli/src/components/tools/__tests__/run-terminal-command.test.ts

@@ -8,11 +8,12 @@ import type { ToolBlock } from '../types'
 const createToolBlock = (
   command: string,
   output?: string,
+  timeoutSeconds?: number,
 ): ToolBlock & { toolName: 'run_terminal_command' } => ({
   type: 'tool',
   toolName: 'run_terminal_command',
   toolCallId: 'test-tool-call-id',
-  input: { command },
+  input: { command, ...(timeoutSeconds !== undefined && { timeout_seconds: timeoutSeconds }) },
   output,
 })
 
@@ -144,6 +145,39 @@ describe('RunTerminalCommandComponent', () => {
     })
   })
 
+  describe('timeout extraction', () => {
+    const mockTheme = {} as any
+    const mockOptions = {
+      availableWidth: 80,
+      indentationOffset: 0,
+      labelWidth: 10,
+    }
+
+    test('passes undefined timeoutSeconds when timeout_seconds not provided', () => {
+      const toolBlock = createToolBlock('ls -la', createJsonOutput('output'))
+
+      const result = RunTerminalCommandComponent.render(toolBlock, mockTheme, mockOptions)
+
+      expect((result.content as any).props.timeoutSeconds).toBeUndefined()
+    })
+
+    test('passes timeoutSeconds for positive timeout', () => {
+      const toolBlock = createToolBlock('npm test', createJsonOutput('tests passed'), 60)
+
+      const result = RunTerminalCommandComponent.render(toolBlock, mockTheme, mockOptions)
+
+      expect((result.content as any).props.timeoutSeconds).toBe(60)
+    })
+
+    test('passes timeoutSeconds for no timeout (-1)', () => {
+      const toolBlock = createToolBlock('long-running-task', createJsonOutput('done'), -1)
+
+      const result = RunTerminalCommandComponent.render(toolBlock, mockTheme, mockOptions)
+
+      expect((result.content as any).props.timeoutSeconds).toBe(-1)
+    })
+  })
+
   describe('parseTerminalOutput', () => {
     test('handles error messages', () => {
       const errorPayload = JSON.stringify([

cli/src/components/tools/run-terminal-command.tsx

@@ -50,11 +50,10 @@ export const RunTerminalCommandComponent = defineToolComponent({
   toolName: 'run_terminal_command',
 
   render(toolBlock): ToolRenderConfig {
-    // Extract command from input
-    const command =
-      toolBlock.input && typeof (toolBlock.input as any).command === 'string'
-        ? (toolBlock.input as any).command.trim()
-        : ''
+    // Extract command and timeout from input
+    const input = toolBlock.input as { command?: string; timeout_seconds?: number } | undefined
+    const command = typeof input?.command === 'string' ? input.command.trim() : ''
+    const timeoutSeconds = typeof input?.timeout_seconds === 'number' ? input.timeout_seconds : undefined
 
     // Extract output and startingCwd from tool result
     const { output, startingCwd } = parseTerminalOutput(toolBlock.output)
@@ -67,6 +66,7 @@ export const RunTerminalCommandComponent = defineToolComponent({
         expandable={true}
         maxVisibleLines={5}
         cwd={startingCwd}
+        timeoutSeconds={timeoutSeconds}
       />
     )
 

cli/src/utils/__tests__/format-timeout.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'bun:test'
+
+import { formatTimeout } from '../format-timeout'
+
+describe('formatTimeout', () => {
+  describe('normal values', () => {
+    test('returns seconds for values less than 60', () => {
+      expect(formatTimeout(10)).toBe('10s timeout')
+      expect(formatTimeout(30)).toBe('30s timeout')
+      expect(formatTimeout(45)).toBe('45s timeout')
+    })
+
+    test('returns minutes for values evenly divisible by 60', () => {
+      expect(formatTimeout(60)).toBe('1m timeout')
+      expect(formatTimeout(120)).toBe('2m timeout')
+      expect(formatTimeout(300)).toBe('5m timeout')
+    })
+
+    test('returns hours for values evenly divisible by 3600', () => {
+      expect(formatTimeout(3600)).toBe('1h timeout')
+      expect(formatTimeout(7200)).toBe('2h timeout')
+      expect(formatTimeout(10800)).toBe('3h timeout')
+    })
+
+    test('returns minutes for large values divisible by 60 but not 3600', () => {
+      expect(formatTimeout(5400)).toBe('90m timeout')
+    })
+
+    test('returns seconds for large values not evenly divisible by 60', () => {
+      expect(formatTimeout(3700)).toBe('3700s timeout')
+    })
+
+    test('returns seconds for values >= 60 not evenly divisible by 60', () => {
+      expect(formatTimeout(90)).toBe('90s timeout')
+      expect(formatTimeout(150)).toBe('150s timeout')
+    })
+
+    test('returns "0s timeout" for 0', () => {
+      expect(formatTimeout(0)).toBe('0s timeout')
+    })
+  })
+
+  describe('negative values', () => {
+    test('returns "no timeout" for -1', () => {
+      expect(formatTimeout(-1)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for other negative values', () => {
+      expect(formatTimeout(-5)).toBe('no timeout')
+      expect(formatTimeout(-100)).toBe('no timeout')
+      expect(formatTimeout(-0.5)).toBe('no timeout')
+    })
+  })
+
+  describe('non-finite values', () => {
+    test('returns "no timeout" for NaN', () => {
+      expect(formatTimeout(NaN)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for Infinity', () => {
+      expect(formatTimeout(Infinity)).toBe('no timeout')
+    })
+
+    test('returns "no timeout" for -Infinity', () => {
+      expect(formatTimeout(-Infinity)).toBe('no timeout')
+    })
+  })
+
+  describe('floating point values', () => {
+    test('rounds floating point values to nearest integer', () => {
+      expect(formatTimeout(30.4)).toBe('30s timeout')
+      expect(formatTimeout(30.5)).toBe('31s timeout')
+      expect(formatTimeout(30.9)).toBe('31s timeout')
+    })
+
+    test('rounds floating point values for minute display', () => {
+      expect(formatTimeout(59.5)).toBe('1m timeout')
+      expect(formatTimeout(60.4)).toBe('1m timeout')
+      expect(formatTimeout(119.6)).toBe('2m timeout')
+    })
+
+    test('handles floating point values that round to non-minute values', () => {
+      expect(formatTimeout(60.6)).toBe('61s timeout')
+      expect(formatTimeout(89.5)).toBe('90s timeout')
+    })
+  })
+})

cli/src/utils/format-timeout.ts

@@ -0,0 +1,28 @@
+/**
+ * Formats a timeout value for display.
+ * - Returns "no timeout" for non-finite values (NaN, Infinity, -Infinity)
+ * - Returns "no timeout" for negative values (including -1)
+ * - Returns hours (e.g., "1h timeout") for values >= 3600 that are evenly divisible by 3600
+ * - Returns minutes (e.g., "2m timeout") for values >= 60 that are evenly divisible by 60
+ * - Returns seconds (e.g., "90s timeout") otherwise
+ * - Rounds floating point values to nearest integer
+ */
+export function formatTimeout(timeoutSeconds: number): string {
+  // Handle NaN, Infinity, -Infinity
+  if (!Number.isFinite(timeoutSeconds)) {
+    return 'no timeout'
+  }
+  // Handle all negative values (including -1)
+  if (timeoutSeconds < 0) {
+    return 'no timeout'
+  }
+  // Round floating point values
+  const rounded = Math.round(timeoutSeconds)
+  if (rounded >= 3600 && rounded % 3600 === 0) {
+    return `${rounded / 3600}h timeout`
+  }
+  if (rounded >= 60 && rounded % 60 === 0) {
+    return `${rounded / 60}m timeout`
+  }
+  return `${rounded}s timeout`
+}