subagent-cli 0.3.0 → 0.3.1

package/src/utils/sideQuestion.ts

@@ -1,155 +0,0 @@
-/**
- * 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/src/utils/signal.ts

@@ -1,43 +0,0 @@
-/**
- * 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/src/utils/sinks.ts

@@ -1,16 +0,0 @@
-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/src/utils/skills/skillChangeDetector.ts

@@ -1,311 +0,0 @@
-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/src/utils/slashCommandParsing.ts

@@ -1,60 +0,0 @@
-/**
- * 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/src/utils/sleep.ts

@@ -1,84 +0,0 @@
-/**
- * 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)
-  })
-}