@xortex/xcode 3.0.0 → 3.0.2

package/hooks/useSearchInput.ts

@@ -0,0 +1,364 @@
+import { useCallback, useState } from 'react'
+import { KeyboardEvent } from '../ink/events/keyboard-event.js'
+// eslint-disable-next-line custom-rules/prefer-use-keybindings -- backward-compat bridge until consumers wire handleKeyDown to <Box onKeyDown>
+import { useInput } from '../ink.js'
+import {
+  Cursor,
+  getLastKill,
+  pushToKillRing,
+  recordYank,
+  resetKillAccumulation,
+  resetYankState,
+  updateYankLength,
+  yankPop,
+} from '../utils/Cursor.js'
+import { useTerminalSize } from './useTerminalSize.js'
+
+type UseSearchInputOptions = {
+  isActive: boolean
+  onExit: () => void
+  /** Esc + Ctrl+C abandon (distinct from onExit = Enter commit). When
+   *  provided: single-Esc calls this directly (no clear-first-then-exit
+   *  two-press). When absent: current behavior — Esc clears non-empty
+   *  query, exits on empty; Ctrl+C silently swallowed (no switch case). */
+  onCancel?: () => void
+  onExitUp?: () => void
+  columns?: number
+  passthroughCtrlKeys?: string[]
+  initialQuery?: string
+  /** Backspace (and ctrl+h) on empty query calls onCancel ?? onExit — the
+   *  less/vim "delete past the /" convention. Dialogs that want Esc-only
+   *  cancel set this false so a held backspace doesn't eject the user. */
+  backspaceExitsOnEmpty?: boolean
+}
+
+type UseSearchInputReturn = {
+  query: string
+  setQuery: (q: string) => void
+  cursorOffset: number
+  handleKeyDown: (e: KeyboardEvent) => void
+}
+
+function isKillKey(e: KeyboardEvent): boolean {
+  if (e.ctrl && (e.key === 'k' || e.key === 'u' || e.key === 'w')) {
+    return true
+  }
+  if (e.meta && e.key === 'backspace') {
+    return true
+  }
+  return false
+}
+
+function isYankKey(e: KeyboardEvent): boolean {
+  return (e.ctrl || e.meta) && e.key === 'y'
+}
+
+// Special key names that fall through the explicit handlers above the
+// text-input branch (return/escape/arrows/home/end/tab/backspace/delete
+// all early-return). Reject these so e.g. PageUp doesn't leak 'pageup'
+// as literal text. The length>=1 check below is intentionally loose —
+// batched input like stdin.write('abc') arrives as one multi-char e.key,
+// matching the old useInput(input) behavior where cursor.insert(input)
+// inserted the full chunk.
+const UNHANDLED_SPECIAL_KEYS = new Set([
+  'pageup',
+  'pagedown',
+  'insert',
+  'wheelup',
+  'wheeldown',
+  'mouse',
+  'f1',
+  'f2',
+  'f3',
+  'f4',
+  'f5',
+  'f6',
+  'f7',
+  'f8',
+  'f9',
+  'f10',
+  'f11',
+  'f12',
+])
+
+export function useSearchInput({
+  isActive,
+  onExit,
+  onCancel,
+  onExitUp,
+  columns,
+  passthroughCtrlKeys = [],
+  initialQuery = '',
+  backspaceExitsOnEmpty = true,
+}: UseSearchInputOptions): UseSearchInputReturn {
+  const { columns: terminalColumns } = useTerminalSize()
+  const effectiveColumns = columns ?? terminalColumns
+  const [query, setQueryState] = useState(initialQuery)
+  const [cursorOffset, setCursorOffset] = useState(initialQuery.length)
+
+  const setQuery = useCallback((q: string) => {
+    setQueryState(q)
+    setCursorOffset(q.length)
+  }, [])
+
+  const handleKeyDown = (e: KeyboardEvent): void => {
+    if (!isActive) return
+
+    const cursor = Cursor.fromText(query, effectiveColumns, cursorOffset)
+
+    // Check passthrough ctrl keys
+    if (e.ctrl && passthroughCtrlKeys.includes(e.key.toLowerCase())) {
+      return
+    }
+
+    // Reset kill accumulation for non-kill keys
+    if (!isKillKey(e)) {
+      resetKillAccumulation()
+    }
+
+    // Reset yank state for non-yank keys
+    if (!isYankKey(e)) {
+      resetYankState()
+    }
+
+    // Exit conditions
+    if (e.key === 'return' || e.key === 'down') {
+      e.preventDefault()
+      onExit()
+      return
+    }
+    if (e.key === 'up') {
+      e.preventDefault()
+      if (onExitUp) {
+        onExitUp()
+      }
+      return
+    }
+    if (e.key === 'escape') {
+      e.preventDefault()
+      if (onCancel) {
+        onCancel()
+      } else if (query.length > 0) {
+        setQueryState('')
+        setCursorOffset(0)
+      } else {
+        onExit()
+      }
+      return
+    }
+
+    // Backspace/Delete
+    if (e.key === 'backspace') {
+      e.preventDefault()
+      if (e.meta) {
+        // Meta+Backspace: kill word before
+        const { cursor: newCursor, killed } = cursor.deleteWordBefore()
+        pushToKillRing(killed, 'prepend')
+        setQueryState(newCursor.text)
+        setCursorOffset(newCursor.offset)
+        return
+      }
+      if (query.length === 0) {
+        // Backspace past the / — cancel (clear + snap back), not commit.
+        // less: same. vim: deletes the / and exits command mode.
+        if (backspaceExitsOnEmpty) (onCancel ?? onExit)()
+        return
+      }
+      const newCursor = cursor.backspace()
+      setQueryState(newCursor.text)
+      setCursorOffset(newCursor.offset)
+      return
+    }
+
+    if (e.key === 'delete') {
+      e.preventDefault()
+      const newCursor = cursor.del()
+      setQueryState(newCursor.text)
+      setCursorOffset(newCursor.offset)
+      return
+    }
+
+    // Arrow keys with modifiers (word jump)
+    if (e.key === 'left' && (e.ctrl || e.meta || e.fn)) {
+      e.preventDefault()
+      const newCursor = cursor.prevWord()
+      setCursorOffset(newCursor.offset)
+      return
+    }
+    if (e.key === 'right' && (e.ctrl || e.meta || e.fn)) {
+      e.preventDefault()
+      const newCursor = cursor.nextWord()
+      setCursorOffset(newCursor.offset)
+      return
+    }
+
+    // Plain arrow keys
+    if (e.key === 'left') {
+      e.preventDefault()
+      const newCursor = cursor.left()
+      setCursorOffset(newCursor.offset)
+      return
+    }
+    if (e.key === 'right') {
+      e.preventDefault()
+      const newCursor = cursor.right()
+      setCursorOffset(newCursor.offset)
+      return
+    }
+
+    // Home/End
+    if (e.key === 'home') {
+      e.preventDefault()
+      setCursorOffset(0)
+      return
+    }
+    if (e.key === 'end') {
+      e.preventDefault()
+      setCursorOffset(query.length)
+      return
+    }
+
+    // Ctrl key bindings
+    if (e.ctrl) {
+      e.preventDefault()
+      switch (e.key.toLowerCase()) {
+        case 'a':
+          setCursorOffset(0)
+          return
+        case 'e':
+          setCursorOffset(query.length)
+          return
+        case 'b':
+          setCursorOffset(cursor.left().offset)
+          return
+        case 'f':
+          setCursorOffset(cursor.right().offset)
+          return
+        case 'd': {
+          if (query.length === 0) {
+            ;(onCancel ?? onExit)()
+            return
+          }
+          const newCursor = cursor.del()
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'h': {
+          if (query.length === 0) {
+            if (backspaceExitsOnEmpty) (onCancel ?? onExit)()
+            return
+          }
+          const newCursor = cursor.backspace()
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'k': {
+          const { cursor: newCursor, killed } = cursor.deleteToLineEnd()
+          pushToKillRing(killed, 'append')
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'u': {
+          const { cursor: newCursor, killed } = cursor.deleteToLineStart()
+          pushToKillRing(killed, 'prepend')
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'w': {
+          const { cursor: newCursor, killed } = cursor.deleteWordBefore()
+          pushToKillRing(killed, 'prepend')
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'y': {
+          const text = getLastKill()
+          if (text.length > 0) {
+            const startOffset = cursor.offset
+            const newCursor = cursor.insert(text)
+            recordYank(startOffset, text.length)
+            setQueryState(newCursor.text)
+            setCursorOffset(newCursor.offset)
+          }
+          return
+        }
+        case 'g':
+        case 'c':
+          // Cancel (abandon search). ctrl+g is less's cancel key. Only
+          // fires if onCancel provided — otherwise falls through and
+          // returns silently (11 call sites, most expect ctrl+c to no-op).
+          if (onCancel) {
+            onCancel()
+            return
+          }
+      }
+      return
+    }
+
+    // Meta key bindings
+    if (e.meta) {
+      e.preventDefault()
+      switch (e.key.toLowerCase()) {
+        case 'b':
+          setCursorOffset(cursor.prevWord().offset)
+          return
+        case 'f':
+          setCursorOffset(cursor.nextWord().offset)
+          return
+        case 'd': {
+          const newCursor = cursor.deleteWordAfter()
+          setQueryState(newCursor.text)
+          setCursorOffset(newCursor.offset)
+          return
+        }
+        case 'y': {
+          const popResult = yankPop()
+          if (popResult) {
+            const { text, start, length } = popResult
+            const before = query.slice(0, start)
+            const after = query.slice(start + length)
+            const newText = before + text + after
+            const newOffset = start + text.length
+            updateYankLength(text.length)
+            setQueryState(newText)
+            setCursorOffset(newOffset)
+          }
+          return
+        }
+      }
+      return
+    }
+
+    // Tab: ignore
+    if (e.key === 'tab') {
+      return
+    }
+
+    // Regular character input. Accepts multi-char e.key so batched writes
+    // (stdin.write('abc') in tests, or paste outside bracketed-paste mode)
+    // insert the full chunk — matching the old useInput behavior.
+    if (e.key.length >= 1 && !UNHANDLED_SPECIAL_KEYS.has(e.key)) {
+      e.preventDefault()
+      const newCursor = cursor.insert(e.key)
+      setQueryState(newCursor.text)
+      setCursorOffset(newCursor.offset)
+    }
+  }
+
+  // Backward-compat bridge: existing consumers don't yet wire handleKeyDown
+  // to <Box onKeyDown>. Subscribe via useInput and adapt InputEvent →
+  // KeyboardEvent until all 11 call sites are migrated (separate PRs).
+  // TODO(onKeyDown-migration): remove once all consumers pass handleKeyDown.
+  useInput(
+    (_input, _key, event) => {
+      handleKeyDown(new KeyboardEvent(event.keypress))
+    },
+    { isActive },
+  )
+
+  return { query, setQuery, cursorOffset, handleKeyDown }
+}

package/hooks/useSessionBackgrounding.ts

@@ -0,0 +1,158 @@
+/**
+ * Hook for managing session backgrounding (Ctrl+B to background/foreground sessions).
+ *
+ * Handles:
+ * - Calling onBackgroundQuery to spawn a background task for the current query
+ * - Re-backgrounding foregrounded tasks
+ * - Syncing foregrounded task messages/state to main view
+ */
+
+import { useCallback, useEffect, useRef } from 'react'
+import { useAppState, useSetAppState } from '../state/AppState.js'
+import type { Message } from '../types/message.js'
+
+type UseSessionBackgroundingProps = {
+  setMessages: (messages: Message[] | ((prev: Message[]) => Message[])) => void
+  setIsLoading: (loading: boolean) => void
+  resetLoadingState: () => void
+  setAbortController: (controller: AbortController | null) => void
+  onBackgroundQuery: () => void
+}
+
+type UseSessionBackgroundingResult = {
+  /** Call when user wants to background (Ctrl+B) */
+  handleBackgroundSession: () => void
+}
+
+export function useSessionBackgrounding({
+  setMessages,
+  setIsLoading,
+  resetLoadingState,
+  setAbortController,
+  onBackgroundQuery,
+}: UseSessionBackgroundingProps): UseSessionBackgroundingResult {
+  const foregroundedTaskId = useAppState(s => s.foregroundedTaskId)
+  const foregroundedTask = useAppState(s =>
+    s.foregroundedTaskId ? s.tasks[s.foregroundedTaskId] : undefined,
+  )
+  const setAppState = useSetAppState()
+  const lastSyncedMessagesLengthRef = useRef<number>(0)
+
+  const handleBackgroundSession = useCallback(() => {
+    if (foregroundedTaskId) {
+      // Re-background the foregrounded task
+      setAppState(prev => {
+        const taskId = prev.foregroundedTaskId
+        if (!taskId) return prev
+        const task = prev.tasks[taskId]
+        if (!task) {
+          return { ...prev, foregroundedTaskId: undefined }
+        }
+        return {
+          ...prev,
+          foregroundedTaskId: undefined,
+          tasks: {
+            ...prev.tasks,
+            [taskId]: { ...task, isBackgrounded: true },
+          },
+        }
+      })
+      setMessages([])
+      resetLoadingState()
+      setAbortController(null)
+      return
+    }
+
+    onBackgroundQuery()
+  }, [
+    foregroundedTaskId,
+    setAppState,
+    setMessages,
+    resetLoadingState,
+    setAbortController,
+    onBackgroundQuery,
+  ])
+
+  // Sync foregrounded task's messages and loading state to the main view
+  useEffect(() => {
+    if (!foregroundedTaskId) {
+      // Reset when no foregrounded task
+      lastSyncedMessagesLengthRef.current = 0
+      return
+    }
+
+    if (!foregroundedTask || foregroundedTask.type !== 'local_agent') {
+      setAppState(prev => ({ ...prev, foregroundedTaskId: undefined }))
+      resetLoadingState()
+      lastSyncedMessagesLengthRef.current = 0
+      return
+    }
+
+    // Sync messages from background task to main view
+    // Only update if messages have actually changed to avoid redundant renders
+    const taskMessages = foregroundedTask.messages ?? []
+    if (taskMessages.length !== lastSyncedMessagesLengthRef.current) {
+      lastSyncedMessagesLengthRef.current = taskMessages.length
+      setMessages([...taskMessages])
+    }
+
+    if (foregroundedTask.status === 'running') {
+      // Check if the task was aborted (user pressed Escape)
+      const taskAbortController = foregroundedTask.abortController
+      if (taskAbortController?.signal.aborted) {
+        // Task was aborted - clear foregrounded state immediately
+        setAppState(prev => {
+          if (!prev.foregroundedTaskId) return prev
+          const task = prev.tasks[prev.foregroundedTaskId]
+          if (!task) return { ...prev, foregroundedTaskId: undefined }
+          return {
+            ...prev,
+            foregroundedTaskId: undefined,
+            tasks: {
+              ...prev.tasks,
+              [prev.foregroundedTaskId]: { ...task, isBackgrounded: true },
+            },
+          }
+        })
+        resetLoadingState()
+        setAbortController(null)
+        lastSyncedMessagesLengthRef.current = 0
+        return
+      }
+
+      setIsLoading(true)
+      // Set abort controller to the foregrounded task's controller for Escape handling
+      if (taskAbortController) {
+        setAbortController(taskAbortController)
+      }
+    } else {
+      // Task completed - restore to background and clear foregrounded view
+      setAppState(prev => {
+        const taskId = prev.foregroundedTaskId
+        if (!taskId) return prev
+        const task = prev.tasks[taskId]
+        if (!task) return { ...prev, foregroundedTaskId: undefined }
+        return {
+          ...prev,
+          foregroundedTaskId: undefined,
+          tasks: { ...prev.tasks, [taskId]: { ...task, isBackgrounded: true } },
+        }
+      })
+      resetLoadingState()
+      setAbortController(null)
+      lastSyncedMessagesLengthRef.current = 0
+    }
+  }, [
+    foregroundedTaskId,
+    foregroundedTask,
+    setAppState,
+    setMessages,
+    setIsLoading,
+    resetLoadingState,
+    setAbortController,
+  ])
+
+  return {
+    handleBackgroundSession,
+  }
+}

package/hooks/useSettings.ts

@@ -0,0 +1,17 @@
+import { type AppState, useAppState } from '../state/AppState.js'
+
+/**
+ * Settings type as stored in AppState (DeepImmutable wrapped).
+ * Use this type when you need to annotate variables that hold settings from useSettings().
+ */
+export type ReadonlySettings = AppState['settings']
+
+/**
+ * React hook to access current settings from AppState.
+ * Settings automatically update when files change on disk via settingsChangeDetector.
+ *
+ * Use this instead of getSettings_DEPRECATED() in React components for reactive updates.
+ */
+export function useSettings(): ReadonlySettings {
+  return useAppState(s => s.settings)
+}

package/hooks/useSettingsChange.ts

@@ -0,0 +1,25 @@
+import { useCallback, useEffect } from 'react'
+import { settingsChangeDetector } from '../utils/settings/changeDetector.js'
+import type { SettingSource } from '../utils/settings/constants.js'
+import { getSettings_DEPRECATED } from '../utils/settings/settings.js'
+import type { SettingsJson } from '../utils/settings/types.js'
+
+export function useSettingsChange(
+  onChange: (source: SettingSource, settings: SettingsJson) => void,
+): void {
+  const handleChange = useCallback(
+    (source: SettingSource) => {
+      // Cache is already reset by the notifier (changeDetector.fanOut) —
+      // resetting here caused N-way thrashing with N subscribers: each
+      // cleared the cache, re-read from disk, then the next cleared again.
+      const newSettings = getSettings_DEPRECATED()
+      onChange(source, newSettings)
+    },
+    [onChange],
+  )
+
+  useEffect(
+    () => settingsChangeDetector.subscribe(handleChange),
+    [handleChange],
+  )
+}

package/hooks/useSkillImprovementSurvey.ts

@@ -0,0 +1,105 @@
+import { useCallback, useRef, useState } from 'react'
+import type { FeedbackSurveyResponse } from '../components/FeedbackSurvey/utils.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
+  logEvent,
+} from '../services/analytics/index.js'
+import { useAppState, useSetAppState } from '../state/AppState.js'
+import type { Message } from '../types/message.js'
+import type { SkillUpdate } from '../utils/hooks/skillImprovement.js'
+import { applySkillImprovement } from '../utils/hooks/skillImprovement.js'
+import { createSystemMessage } from '../utils/messages.js'
+
+type SkillImprovementSuggestion = {
+  skillName: string
+  updates: SkillUpdate[]
+}
+
+type SetMessages = (fn: (prev: Message[]) => Message[]) => void
+
+export function useSkillImprovementSurvey(setMessages: SetMessages): {
+  isOpen: boolean
+  suggestion: SkillImprovementSuggestion | null
+  handleSelect: (selected: FeedbackSurveyResponse) => void
+} {
+  const suggestion = useAppState(s => s.skillImprovement.suggestion)
+  const setAppState = useSetAppState()
+  const [isOpen, setIsOpen] = useState(false)
+  const lastSuggestionRef = useRef(suggestion)
+  const loggedAppearanceRef = useRef(false)
+
+  // Track the suggestion for display even after clearing AppState
+  if (suggestion) {
+    lastSuggestionRef.current = suggestion
+  }
+
+  // Open when a new suggestion arrives
+  if (suggestion && !isOpen) {
+    setIsOpen(true)
+    if (!loggedAppearanceRef.current) {
+      loggedAppearanceRef.current = true
+      logEvent('tengu_skill_improvement_survey', {
+        event_type:
+          'appeared' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        // _PROTO_skill_name routes to the privileged skill_name BQ column.
+        // Unredacted names don't go in additional_metadata.
+        _PROTO_skill_name: (suggestion.skillName ??
+          'unknown') as AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
+      })
+    }
+  }
+
+  const handleSelect = useCallback(
+    (selected: FeedbackSurveyResponse) => {
+      const current = lastSuggestionRef.current
+      if (!current) return
+
+      const applied = selected !== 'dismissed'
+
+      logEvent('tengu_skill_improvement_survey', {
+        event_type:
+          'responded' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        response: (applied
+          ? 'applied'
+          : 'dismissed') as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        // _PROTO_skill_name routes to the privileged skill_name BQ column.
+        // Unredacted names don't go in additional_metadata.
+        _PROTO_skill_name:
+          current.skillName as AnalyticsMetadata_I_VERIFIED_THIS_IS_PII_TAGGED,
+      })
+
+      if (applied) {
+        void applySkillImprovement(current.skillName, current.updates).then(
+          () => {
+            setMessages(prev => [
+              ...prev,
+              createSystemMessage(
+                `Skill "${current.skillName}" updated with improvements.`,
+                'suggestion',
+              ),
+            ])
+          },
+        )
+      }
+
+      // Close and clear
+      setIsOpen(false)
+      loggedAppearanceRef.current = false
+      setAppState(prev => {
+        if (!prev.skillImprovement.suggestion) return prev
+        return {
+          ...prev,
+          skillImprovement: { suggestion: null },
+        }
+      })
+    },
+    [setAppState, setMessages],
+  )
+
+  return {
+    isOpen,
+    suggestion: lastSuggestionRef.current,
+    handleSelect,
+  }
+}