@xortex/xcode 3.0.0

package/utils/sideQuestion.ts

@@ -0,0 +1,155 @@
+/**
+ * Side Question ("/btw") feature - allows asking quick questions without
+ * interrupting the main agent context.
+ *
+ * Uses runForkedAgent to leverage prompt caching from the parent context
+ * while keeping the side question response separate from main conversation.
+ */
+
+import { formatAPIError } from '../services/api/errorUtils.js'
+import type { NonNullableUsage } from '../services/api/logging.js'
+import type { Message, SystemAPIErrorMessage } from '../types/message.js'
+import { type CacheSafeParams, runForkedAgent } from './forkedAgent.js'
+import { createUserMessage, extractTextContent } from './messages.js'
+
+// Pattern to detect "/btw" at start of input (case-insensitive, word boundary)
+const BTW_PATTERN = /^\/btw\b/gi
+
+/**
+ * Find positions of "/btw" keyword at the start of text for highlighting.
+ * Similar to findThinkingTriggerPositions in thinking.ts.
+ */
+export function findBtwTriggerPositions(text: string): Array<{
+  word: string
+  start: number
+  end: number
+}> {
+  const positions: Array<{ word: string; start: number; end: number }> = []
+  const matches = text.matchAll(BTW_PATTERN)
+
+  for (const match of matches) {
+    if (match.index !== undefined) {
+      positions.push({
+        word: match[0],
+        start: match.index,
+        end: match.index + match[0].length,
+      })
+    }
+  }
+
+  return positions
+}
+
+export type SideQuestionResult = {
+  response: string | null
+  usage: NonNullableUsage
+}
+
+/**
+ * Run a side question using a forked agent.
+ * Shares the parent's prompt cache — no thinking override, no cache write.
+ * All tools are blocked and we cap at 1 turn.
+ */
+export async function runSideQuestion({
+  question,
+  cacheSafeParams,
+}: {
+  question: string
+  cacheSafeParams: CacheSafeParams
+}): Promise<SideQuestionResult> {
+  // Wrap the question with instructions to answer without tools
+  const wrappedQuestion = `<system-reminder>This is a side question from the user. You must answer this question directly in a single response.
+
+IMPORTANT CONTEXT:
+- You are a separate, lightweight agent spawned to answer this one question
+- The main agent is NOT interrupted - it continues working independently in the background
+- You share the conversation context but are a completely separate instance
+- Do NOT reference being interrupted or what you were "previously doing" - that framing is incorrect
+
+CRITICAL CONSTRAINTS:
+- You have NO tools available - you cannot read files, run commands, search, or take any actions
+- This is a one-off response - there will be no follow-up turns
+- You can ONLY provide information based on what you already know from the conversation context
+- NEVER say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action
+- If you don't know the answer, say so - do not offer to look it up or investigate
+
+Simply answer the question with the information you have.</system-reminder>
+
+${question}`
+
+  const agentResult = await runForkedAgent({
+    promptMessages: [createUserMessage({ content: wrappedQuestion })],
+    // Do NOT override thinkingConfig — thinking is part of the API cache key,
+    // and diverging from the main thread's config busts the prompt cache.
+    // Adaptive thinking on a quick Q&A has negligible overhead.
+    cacheSafeParams,
+    canUseTool: async () => ({
+      behavior: 'deny' as const,
+      message: 'Side questions cannot use tools',
+      decisionReason: { type: 'other' as const, reason: 'side_question' },
+    }),
+    querySource: 'side_question',
+    forkLabel: 'side_question',
+    maxTurns: 1, // Single turn only - no tool use loops
+    // No future request shares this suffix; skip writing cache entries.
+    skipCacheWrite: true,
+  })
+
+  return {
+    response: extractSideQuestionResponse(agentResult.messages),
+    usage: agentResult.totalUsage,
+  }
+}
+
+/**
+ * Extract a display string from forked agent messages.
+ *
+ * IMPORTANT: claude.ts yields one AssistantMessage PER CONTENT BLOCK, not one
+ * per API response. With adaptive thinking enabled (inherited from the main
+ * thread to preserve the cache key), a thinking response arrives as:
+ *   messages[0] = assistant { content: [thinking_block] }
+ *   messages[1] = assistant { content: [text_block] }
+ *
+ * The old code used `.find(m => m.type === 'assistant')` which grabbed the
+ * first (thinking-only) message, found no text block, and returned null →
+ * "No response received". Repos with large context (many skills, big CLAUDE.md)
+ * trigger thinking more often, which is why this reproduced in the monorepo
+ * but not here.
+ *
+ * Secondary failure modes also surfaced as "No response received":
+ *   - Model attempts tool_use → content = [thinking, tool_use], no text.
+ *     Rare — the system-reminder usually prevents this, but handled here.
+ *   - API error exhausts retries → query yields system api_error + user
+ *     interruption, no assistant message at all.
+ */
+function extractSideQuestionResponse(messages: Message[]): string | null {
+  // Flatten all assistant content blocks across the per-block messages.
+  const assistantBlocks = messages.flatMap(m =>
+    m.type === 'assistant' ? m.message.content : [],
+  )
+
+  if (assistantBlocks.length > 0) {
+    // Concatenate all text blocks (there's normally at most one, but be safe).
+    const text = extractTextContent(assistantBlocks, '\n\n').trim()
+    if (text) return text
+
+    // No text — check if the model tried to call a tool despite instructions.
+    const toolUse = assistantBlocks.find(b => b.type === 'tool_use')
+    if (toolUse) {
+      const toolName = 'name' in toolUse ? toolUse.name : 'a tool'
+      return `(The model tried to call ${toolName} instead of answering directly. Try rephrasing or ask in the main conversation.)`
+    }
+  }
+
+  // No assistant content — likely API error exhausted retries. Surface the
+  // first system api_error message so the user sees what happened.
+  const apiErr = messages.find(
+    (m): m is SystemAPIErrorMessage =>
+      m.type === 'system' && 'subtype' in m && m.subtype === 'api_error',
+  )
+  if (apiErr) {
+    return `(API error: ${formatAPIError(apiErr.error)})`
+  }
+
+  return null
+}

package/utils/signal.ts

@@ -0,0 +1,43 @@
+/**
+ * Tiny listener-set primitive for pure event signals (no stored state).
+ *
+ * Collapses the ~8-line `const listeners = new Set(); function subscribe(){…};
+ * function notify(){for(const l of listeners) l()}` boilerplate that was
+ * duplicated ~15× across the codebase into a one-liner.
+ *
+ * Distinct from a store (AppState, createStore) — there is no snapshot, no
+ * getState. Use this when subscribers only need to know "something happened",
+ * optionally with event args, not "what is the current value".
+ *
+ * Usage:
+ *   const changed = createSignal<[SettingSource]>()
+ *   export const subscribe = changed.subscribe
+ *   // later: changed.emit('userSettings')
+ */
+
+export type Signal<Args extends unknown[] = []> = {
+  /** Subscribe a listener. Returns an unsubscribe function. */
+  subscribe: (listener: (...args: Args) => void) => () => void
+  /** Call all subscribed listeners with the given arguments. */
+  emit: (...args: Args) => void
+  /** Remove all listeners. Useful in dispose/reset paths. */
+  clear: () => void
+}
+
+export function createSignal<Args extends unknown[] = []>(): Signal<Args> {
+  const listeners = new Set<(...args: Args) => void>()
+  return {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    emit(...args) {
+      for (const listener of listeners) listener(...args)
+    },
+    clear() {
+      listeners.clear()
+    },
+  }
+}

package/utils/sinks.ts

@@ -0,0 +1,16 @@
+import { initializeAnalyticsSink } from '../services/analytics/sink.js'
+import { initializeErrorLogSink } from './errorLogSink.js'
+
+/**
+ * Attach error log and analytics sinks, draining any events queued before
+ * attachment. Both inits are idempotent. Called from setup() for the default
+ * command; other entrypoints (subcommands, daemon, bridge) call this directly
+ * since they bypass setup().
+ *
+ * Leaf module — kept out of setup.ts to avoid the setup → commands → bridge
+ * → setup import cycle.
+ */
+export function initSinks(): void {
+  initializeErrorLogSink()
+  initializeAnalyticsSink()
+}

package/utils/skills/skillChangeDetector.ts

@@ -0,0 +1,311 @@
+import chokidar, { type FSWatcher } from 'chokidar'
+import * as platformPath from 'path'
+import { getAdditionalDirectoriesForClaudeMd } from '../../bootstrap/state.js'
+import {
+  clearCommandMemoizationCaches,
+  clearCommandsCache,
+} from '../../commands.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../../services/analytics/index.js'
+import {
+  clearSkillCaches,
+  getSkillsPath,
+  onDynamicSkillsLoaded,
+} from '../../skills/loadSkillsDir.js'
+import { resetSentSkillNames } from '../attachments.js'
+import { registerCleanup } from '../cleanupRegistry.js'
+import { logForDebugging } from '../debug.js'
+import { getFsImplementation } from '../fsOperations.js'
+import { executeConfigChangeHooks, hasBlockingResult } from '../hooks.js'
+import { createSignal } from '../signal.js'
+
+/**
+ * Time in milliseconds to wait for file writes to stabilize before processing.
+ */
+const FILE_STABILITY_THRESHOLD_MS = 1000
+
+/**
+ * Polling interval in milliseconds for checking file stability.
+ */
+const FILE_STABILITY_POLL_INTERVAL_MS = 500
+
+/**
+ * Time in milliseconds to debounce rapid skill change events into a single
+ * reload. Prevents cascading reloads when many skill files change at once
+ * (e.g. during auto-update or when another session modifies skill directories).
+ * Without this, each file change triggers a full clearSkillCaches() +
+ * clearCommandsCache() + listener notification cycle, which can deadlock the
+ * event loop when dozens of events fire in rapid succession.
+ */
+const RELOAD_DEBOUNCE_MS = 300
+
+/**
+ * Polling interval for chokidar when usePolling is enabled.
+ * Skill files change rarely (manual edits, git operations), so a 2s interval
+ * trades negligible latency for far fewer stat() calls than the default 100ms.
+ */
+const POLLING_INTERVAL_MS = 2000
+
+/**
+ * Bun's native fs.watch() has a PathWatcherManager deadlock (oven-sh/bun#27469,
+ * #26385): closing a watcher on the main thread while the File Watcher thread
+ * is delivering events can hang both threads in __ulock_wait2 forever. Chokidar
+ * with depth: 2 on large skill trees (hundreds of subdirs) triggers this
+ * reliably when a git operation touches many directories at once — chokidar
+ * internally closes/reopens per-directory FSWatchers as dirs are added/removed.
+ *
+ * Workaround: use stat() polling under Bun. No FSWatcher = no deadlock.
+ * The fix is pending upstream; remove this once the Bun PR lands.
+ */
+const USE_POLLING = typeof Bun !== 'undefined'
+
+let watcher: FSWatcher | null = null
+let reloadTimer: ReturnType<typeof setTimeout> | null = null
+const pendingChangedPaths = new Set<string>()
+let initialized = false
+let disposed = false
+let dynamicSkillsCallbackRegistered = false
+let unregisterCleanup: (() => void) | null = null
+const skillsChanged = createSignal()
+
+// Test overrides for timing constants
+let testOverrides: {
+  stabilityThreshold?: number
+  pollInterval?: number
+  reloadDebounce?: number
+  /** Chokidar fs.stat polling interval when USE_POLLING is active. */
+  chokidarInterval?: number
+} | null = null
+
+/**
+ * Initialize file watching for skill directories
+ */
+export async function initialize(): Promise<void> {
+  if (initialized || disposed) return
+  initialized = true
+
+  // Register callback for when dynamic skills are loaded (only once)
+  if (!dynamicSkillsCallbackRegistered) {
+    dynamicSkillsCallbackRegistered = true
+    onDynamicSkillsLoaded(() => {
+      // Clear memoization caches so new skills are picked up
+      // Note: we use clearCommandMemoizationCaches (not clearCommandsCache)
+      // because clearCommandsCache would call clearSkillCaches which
+      // wipes out the dynamic skills we just loaded
+      clearCommandMemoizationCaches()
+      // Notify listeners that skills changed
+      skillsChanged.emit()
+    })
+  }
+
+  const paths = await getWatchablePaths()
+  if (paths.length === 0) return
+
+  logForDebugging(
+    `Watching for changes in skill/command directories: ${paths.join(', ')}...`,
+  )
+
+  watcher = chokidar.watch(paths, {
+    persistent: true,
+    ignoreInitial: true,
+    depth: 2, // Skills use skill-name/SKILL.md format
+    awaitWriteFinish: {
+      stabilityThreshold:
+        testOverrides?.stabilityThreshold ?? FILE_STABILITY_THRESHOLD_MS,
+      pollInterval:
+        testOverrides?.pollInterval ?? FILE_STABILITY_POLL_INTERVAL_MS,
+    },
+    // Ignore special file types (sockets, FIFOs, devices) - they cannot be watched
+    // and will error with EOPNOTSUPP on macOS. Only allow regular files and directories.
+    ignored: (path, stats) => {
+      if (stats && !stats.isFile() && !stats.isDirectory()) return true
+      // Ignore .git directories
+      return path.split(platformPath.sep).some(dir => dir === '.git')
+    },
+    ignorePermissionErrors: true,
+    usePolling: USE_POLLING,
+    interval: testOverrides?.chokidarInterval ?? POLLING_INTERVAL_MS,
+    atomic: true,
+  })
+
+  watcher.on('add', handleChange)
+  watcher.on('change', handleChange)
+  watcher.on('unlink', handleChange)
+
+  // Register cleanup to properly dispose of the file watcher during graceful shutdown
+  unregisterCleanup = registerCleanup(async () => {
+    await dispose()
+  })
+}
+
+/**
+ * Clean up file watcher
+ */
+export function dispose(): Promise<void> {
+  disposed = true
+  if (unregisterCleanup) {
+    unregisterCleanup()
+    unregisterCleanup = null
+  }
+  let closePromise: Promise<void> = Promise.resolve()
+  if (watcher) {
+    closePromise = watcher.close()
+    watcher = null
+  }
+  if (reloadTimer) {
+    clearTimeout(reloadTimer)
+    reloadTimer = null
+  }
+  pendingChangedPaths.clear()
+  skillsChanged.clear()
+  return closePromise
+}
+
+/**
+ * Subscribe to skill changes
+ */
+export const subscribe = skillsChanged.subscribe
+
+async function getWatchablePaths(): Promise<string[]> {
+  const fs = getFsImplementation()
+  const paths: string[] = []
+
+  // User skills directory (~/.claude/skills)
+  const userSkillsPath = getSkillsPath('userSettings', 'skills')
+  if (userSkillsPath) {
+    try {
+      await fs.stat(userSkillsPath)
+      paths.push(userSkillsPath)
+    } catch {
+      // Path doesn't exist, skip it
+    }
+  }
+
+  // User commands directory (~/.claude/commands)
+  const userCommandsPath = getSkillsPath('userSettings', 'commands')
+  if (userCommandsPath) {
+    try {
+      await fs.stat(userCommandsPath)
+      paths.push(userCommandsPath)
+    } catch {
+      // Path doesn't exist, skip it
+    }
+  }
+
+  // Project skills directory (.claude/skills)
+  const projectSkillsPath = getSkillsPath('projectSettings', 'skills')
+  if (projectSkillsPath) {
+    try {
+      // For project settings, resolve to absolute path
+      const absolutePath = platformPath.resolve(projectSkillsPath)
+      await fs.stat(absolutePath)
+      paths.push(absolutePath)
+    } catch {
+      // Path doesn't exist, skip it
+    }
+  }
+
+  // Project commands directory (.claude/commands)
+  const projectCommandsPath = getSkillsPath('projectSettings', 'commands')
+  if (projectCommandsPath) {
+    try {
+      // For project settings, resolve to absolute path
+      const absolutePath = platformPath.resolve(projectCommandsPath)
+      await fs.stat(absolutePath)
+      paths.push(absolutePath)
+    } catch {
+      // Path doesn't exist, skip it
+    }
+  }
+
+  // Additional directories (--add-dir) skills
+  for (const dir of getAdditionalDirectoriesForClaudeMd()) {
+    const additionalSkillsPath = platformPath.join(dir, '.claude', 'skills')
+    try {
+      await fs.stat(additionalSkillsPath)
+      paths.push(additionalSkillsPath)
+    } catch {
+      // Path doesn't exist, skip it
+    }
+  }
+
+  return paths
+}
+
+function handleChange(path: string): void {
+  logForDebugging(`Detected skill change: ${path}`)
+  logEvent('tengu_skill_file_changed', {
+    source:
+      'chokidar' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  })
+
+  scheduleReload(path)
+}
+
+/**
+ * Debounce rapid skill changes into a single reload. When many skill files
+ * change at once (e.g. auto-update installs a new binary and a new session
+ * touches skill directories), each file fires its own chokidar event. Without
+ * debouncing, each event triggers clearSkillCaches() + clearCommandsCache() +
+ * listener notification — 30 events means 30 full reload cycles, which can
+ * deadlock the Bun event loop via rapid FSWatcher watch/unwatch churn.
+ */
+function scheduleReload(changedPath: string): void {
+  pendingChangedPaths.add(changedPath)
+  if (reloadTimer) clearTimeout(reloadTimer)
+  reloadTimer = setTimeout(async () => {
+    reloadTimer = null
+    const paths = [...pendingChangedPaths]
+    pendingChangedPaths.clear()
+    // Fire ConfigChange hook once for the batch — the hook query is always
+    // 'skills' so firing per-path (which can be hundreds during a git
+    // operation) just spams the hook matcher with identical queries. Pass the
+    // first path as a representative; hooks can inspect all paths via the
+    // skills directory if they need the full set.
+    const results = await executeConfigChangeHooks('skills', paths[0]!)
+    if (hasBlockingResult(results)) {
+      logForDebugging(
+        `ConfigChange hook blocked skill reload (${paths.length} paths)`,
+      )
+      return
+    }
+    clearSkillCaches()
+    clearCommandsCache()
+    resetSentSkillNames()
+    skillsChanged.emit()
+  }, testOverrides?.reloadDebounce ?? RELOAD_DEBOUNCE_MS)
+}
+
+/**
+ * Reset internal state for testing purposes only.
+ */
+export async function resetForTesting(overrides?: {
+  stabilityThreshold?: number
+  pollInterval?: number
+  reloadDebounce?: number
+  chokidarInterval?: number
+}): Promise<void> {
+  // Clean up existing watcher if present to avoid resource leaks
+  if (watcher) {
+    await watcher.close()
+    watcher = null
+  }
+  if (reloadTimer) {
+    clearTimeout(reloadTimer)
+    reloadTimer = null
+  }
+  pendingChangedPaths.clear()
+  skillsChanged.clear()
+  initialized = false
+  disposed = false
+  testOverrides = overrides ?? null
+}
+
+export const skillChangeDetector = {
+  initialize,
+  dispose,
+  subscribe,
+  resetForTesting,
+}

package/utils/slashCommandParsing.ts

@@ -0,0 +1,60 @@
+/**
+ * Centralized utilities for parsing slash commands
+ */
+
+export type ParsedSlashCommand = {
+  commandName: string
+  args: string
+  isMcp: boolean
+}
+
+/**
+ * Parses a slash command input string into its component parts
+ *
+ * @param input - The raw input string (should start with '/')
+ * @returns Parsed command name, args, and MCP flag, or null if invalid
+ *
+ * @example
+ * parseSlashCommand('/search foo bar')
+ * // => { commandName: 'search', args: 'foo bar', isMcp: false }
+ *
+ * @example
+ * parseSlashCommand('/mcp:tool (MCP) arg1 arg2')
+ * // => { commandName: 'mcp:tool (MCP)', args: 'arg1 arg2', isMcp: true }
+ */
+export function parseSlashCommand(input: string): ParsedSlashCommand | null {
+  const trimmedInput = input.trim()
+
+  // Check if input starts with '/'
+  if (!trimmedInput.startsWith('/')) {
+    return null
+  }
+
+  // Remove the leading '/' and split by spaces
+  const withoutSlash = trimmedInput.slice(1)
+  const words = withoutSlash.split(' ')
+
+  if (!words[0]) {
+    return null
+  }
+
+  let commandName = words[0]
+  let isMcp = false
+  let argsStartIndex = 1
+
+  // Check for MCP commands (second word is '(MCP)')
+  if (words.length > 1 && words[1] === '(MCP)') {
+    commandName = commandName + ' (MCP)'
+    isMcp = true
+    argsStartIndex = 2
+  }
+
+  // Extract arguments (everything after command name)
+  const args = words.slice(argsStartIndex).join(' ')
+
+  return {
+    commandName,
+    args,
+    isMcp,
+  }
+}

package/utils/sleep.ts

@@ -0,0 +1,84 @@
+/**
+ * Abort-responsive sleep. Resolves after `ms` milliseconds, or immediately
+ * when `signal` aborts (so backoff loops don't block shutdown).
+ *
+ * By default, abort resolves silently; the caller should check
+ * `signal.aborted` after the await. Pass `throwOnAbort: true` to have
+ * abort reject — useful when the sleep is deep inside a retry loop
+ * and you want the rejection to bubble up and cancel the whole operation.
+ *
+ * Pass `abortError` to customize the rejection error (implies
+ * `throwOnAbort: true`). Useful for retry loops that catch a specific
+ * error class (e.g. `APIUserAbortError`).
+ */
+export function sleep(
+  ms: number,
+  signal?: AbortSignal,
+  opts?: { throwOnAbort?: boolean; abortError?: () => Error; unref?: boolean },
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Check aborted state BEFORE setting up the timer. If we defined
+    // onAbort first and called it synchronously here, it would reference
+    // `timer` while still in the Temporal Dead Zone.
+    if (signal?.aborted) {
+      if (opts?.throwOnAbort || opts?.abortError) {
+        void reject(opts.abortError?.() ?? new Error('aborted'))
+      } else {
+        void resolve()
+      }
+      return
+    }
+    const timer = setTimeout(
+      (signal, onAbort, resolve) => {
+        signal?.removeEventListener('abort', onAbort)
+        void resolve()
+      },
+      ms,
+      signal,
+      onAbort,
+      resolve,
+    )
+    function onAbort(): void {
+      clearTimeout(timer)
+      if (opts?.throwOnAbort || opts?.abortError) {
+        void reject(opts.abortError?.() ?? new Error('aborted'))
+      } else {
+        void resolve()
+      }
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+    if (opts?.unref) {
+      timer.unref()
+    }
+  })
+}
+
+function rejectWithTimeout(reject: (e: Error) => void, message: string): void {
+  reject(new Error(message))
+}
+
+/**
+ * Race a promise against a timeout. Rejects with `Error(message)` if the
+ * promise doesn't settle within `ms`. The timeout timer is cleared when
+ * the promise settles (no dangling timer) and unref'd so it doesn't
+ * block process exit.
+ *
+ * Note: this doesn't cancel the underlying work — if the promise is
+ * backed by a runaway async operation, that keeps running. This just
+ * returns control to the caller.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    // eslint-disable-next-line no-restricted-syntax -- not a sleep: REJECTS after ms (timeout guard)
+    timer = setTimeout(rejectWithTimeout, ms, reject, message)
+    if (typeof timer === 'object') timer.unref?.()
+  })
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer)
+  })
+}