@xortex/xcode 3.0.0

package/utils/queryProfiler.ts

@@ -0,0 +1,301 @@
+/**
+ * Query profiling utility for measuring and reporting time spent in the query
+ * pipeline from user input to first token arrival. Enable by setting CLAUDE_CODE_PROFILE_QUERY=1
+ *
+ * Uses Node.js built-in performance hooks API for standard timing measurement.
+ * Tracks each query session with detailed checkpoints for identifying bottlenecks.
+ *
+ * Checkpoints tracked (in order):
+ * - query_user_input_received: Start of profiling
+ * - query_context_loading_start/end: Loading system prompts and contexts
+ * - query_query_start: Entry to query call from REPL
+ * - query_fn_entry: Entry to query() function
+ * - query_microcompact_start/end: Microcompaction of messages
+ * - query_autocompact_start/end: Autocompaction check
+ * - query_setup_start/end: StreamingToolExecutor and model setup
+ * - query_api_loop_start: Start of API retry loop
+ * - query_api_streaming_start: Start of streaming API call
+ * - query_tool_schema_build_start/end: Building tool schemas
+ * - query_message_normalization_start/end: Normalizing messages
+ * - query_client_creation_start/end: Creating Anthropic client
+ * - query_api_request_sent: HTTP request dispatched (before await, inside retry body)
+ * - query_response_headers_received: .withResponse() resolved (headers arrived)
+ * - query_first_chunk_received: First streaming chunk received (TTFT)
+ * - query_api_streaming_end: Streaming complete
+ * - query_tool_execution_start/end: Tool execution
+ * - query_recursive_call: Before recursive query call
+ * - query_end: End of query
+ */
+
+import { logForDebugging } from './debug.js'
+import { isEnvTruthy } from './envUtils.js'
+import { formatMs, formatTimelineLine, getPerformance } from './profilerBase.js'
+
+// Module-level state - initialized once when the module loads
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const ENABLED = isEnvTruthy(process.env.CLAUDE_CODE_PROFILE_QUERY)
+
+// Track memory snapshots separately (perf_hooks doesn't track memory)
+const memorySnapshots = new Map<string, NodeJS.MemoryUsage>()
+
+// Track query count for reporting
+let queryCount = 0
+
+// Track first token received time separately for summary
+let firstTokenTime: number | null = null
+
+/**
+ * Start profiling a new query session
+ */
+export function startQueryProfile(): void {
+  if (!ENABLED) return
+
+  const perf = getPerformance()
+
+  // Clear previous marks and memory snapshots
+  perf.clearMarks()
+  memorySnapshots.clear()
+  firstTokenTime = null
+
+  queryCount++
+
+  // Record the start checkpoint
+  queryCheckpoint('query_user_input_received')
+}
+
+/**
+ * Record a checkpoint with the given name
+ */
+export function queryCheckpoint(name: string): void {
+  if (!ENABLED) return
+
+  const perf = getPerformance()
+  perf.mark(name)
+  memorySnapshots.set(name, process.memoryUsage())
+
+  // Track first token specially
+  if (name === 'query_first_chunk_received' && firstTokenTime === null) {
+    const marks = perf.getEntriesByType('mark')
+    if (marks.length > 0) {
+      const lastMark = marks[marks.length - 1]
+      firstTokenTime = lastMark?.startTime ?? 0
+    }
+  }
+}
+
+/**
+ * End the current query profiling session
+ */
+export function endQueryProfile(): void {
+  if (!ENABLED) return
+
+  queryCheckpoint('query_profile_end')
+}
+
+/**
+ * Identify slow operations (> 100ms delta)
+ */
+function getSlowWarning(deltaMs: number, name: string): string {
+  // Don't flag the first checkpoint as slow - it measures time from process start,
+  // not actual processing overhead
+  if (name === 'query_user_input_received') {
+    return ''
+  }
+
+  if (deltaMs > 1000) {
+    return ` ⚠️  VERY SLOW`
+  }
+  if (deltaMs > 100) {
+    return ` ⚠️  SLOW`
+  }
+
+  // Specific warnings for known bottlenecks
+  if (name.includes('git_status') && deltaMs > 50) {
+    return ' ⚠️  git status'
+  }
+  if (name.includes('tool_schema') && deltaMs > 50) {
+    return ' ⚠️  tool schemas'
+  }
+  if (name.includes('client_creation') && deltaMs > 50) {
+    return ' ⚠️  client creation'
+  }
+
+  return ''
+}
+
+/**
+ * Get a formatted report of all checkpoints for the current/last query
+ */
+function getQueryProfileReport(): string {
+  if (!ENABLED) {
+    return 'Query profiling not enabled (set CLAUDE_CODE_PROFILE_QUERY=1)'
+  }
+
+  const perf = getPerformance()
+  const marks = perf.getEntriesByType('mark')
+  if (marks.length === 0) {
+    return 'No query profiling checkpoints recorded'
+  }
+
+  const lines: string[] = []
+  lines.push('='.repeat(80))
+  lines.push(`QUERY PROFILING REPORT - Query #${queryCount}`)
+  lines.push('='.repeat(80))
+  lines.push('')
+
+  // Use first mark as baseline (query start time) to show relative times
+  const baselineTime = marks[0]?.startTime ?? 0
+  let prevTime = baselineTime
+  let apiRequestSentTime = 0
+  let firstChunkTime = 0
+
+  for (const mark of marks) {
+    const relativeTime = mark.startTime - baselineTime
+    const deltaMs = mark.startTime - prevTime
+    lines.push(
+      formatTimelineLine(
+        relativeTime,
+        deltaMs,
+        mark.name,
+        memorySnapshots.get(mark.name),
+        10,
+        9,
+        getSlowWarning(deltaMs, mark.name),
+      ),
+    )
+
+    // Track key milestones for summary (use relative times)
+    if (mark.name === 'query_api_request_sent') {
+      apiRequestSentTime = relativeTime
+    }
+    if (mark.name === 'query_first_chunk_received') {
+      firstChunkTime = relativeTime
+    }
+
+    prevTime = mark.startTime
+  }
+
+  // Calculate summary statistics (relative to baseline)
+  const lastMark = marks[marks.length - 1]
+  const totalTime = lastMark ? lastMark.startTime - baselineTime : 0
+
+  lines.push('')
+  lines.push('-'.repeat(80))
+
+  if (firstChunkTime > 0) {
+    const preRequestOverhead = apiRequestSentTime
+    const networkLatency = firstChunkTime - apiRequestSentTime
+    const preRequestPercent = (
+      (preRequestOverhead / firstChunkTime) *
+      100
+    ).toFixed(1)
+    const networkPercent = ((networkLatency / firstChunkTime) * 100).toFixed(1)
+
+    lines.push(`Total TTFT: ${formatMs(firstChunkTime)}ms`)
+    lines.push(
+      `  - Pre-request overhead: ${formatMs(preRequestOverhead)}ms (${preRequestPercent}%)`,
+    )
+    lines.push(
+      `  - Network latency: ${formatMs(networkLatency)}ms (${networkPercent}%)`,
+    )
+  } else {
+    lines.push(`Total time: ${formatMs(totalTime)}ms`)
+  }
+
+  // Add phase summary
+  lines.push(getPhaseSummary(marks, baselineTime))
+
+  lines.push('='.repeat(80))
+
+  return lines.join('\n')
+}
+
+/**
+ * Get phase-based summary showing time spent in each major phase
+ */
+function getPhaseSummary(
+  marks: Array<{ name: string; startTime: number }>,
+  baselineTime: number,
+): string {
+  const phases: Array<{ name: string; start: string; end: string }> = [
+    {
+      name: 'Context loading',
+      start: 'query_context_loading_start',
+      end: 'query_context_loading_end',
+    },
+    {
+      name: 'Microcompact',
+      start: 'query_microcompact_start',
+      end: 'query_microcompact_end',
+    },
+    {
+      name: 'Autocompact',
+      start: 'query_autocompact_start',
+      end: 'query_autocompact_end',
+    },
+    { name: 'Query setup', start: 'query_setup_start', end: 'query_setup_end' },
+    {
+      name: 'Tool schemas',
+      start: 'query_tool_schema_build_start',
+      end: 'query_tool_schema_build_end',
+    },
+    {
+      name: 'Message normalization',
+      start: 'query_message_normalization_start',
+      end: 'query_message_normalization_end',
+    },
+    {
+      name: 'Client creation',
+      start: 'query_client_creation_start',
+      end: 'query_client_creation_end',
+    },
+    {
+      name: 'Network TTFB',
+      start: 'query_api_request_sent',
+      end: 'query_first_chunk_received',
+    },
+    {
+      name: 'Tool execution',
+      start: 'query_tool_execution_start',
+      end: 'query_tool_execution_end',
+    },
+  ]
+
+  const markMap = new Map(marks.map(m => [m.name, m.startTime - baselineTime]))
+
+  const lines: string[] = []
+  lines.push('')
+  lines.push('PHASE BREAKDOWN:')
+
+  for (const phase of phases) {
+    const startTime = markMap.get(phase.start)
+    const endTime = markMap.get(phase.end)
+
+    if (startTime !== undefined && endTime !== undefined) {
+      const duration = endTime - startTime
+      const bar = '█'.repeat(Math.min(Math.ceil(duration / 10), 50)) // 1 block per 10ms, max 50
+      lines.push(
+        `  ${phase.name.padEnd(22)} ${formatMs(duration).padStart(10)}ms ${bar}`,
+      )
+    }
+  }
+
+  // Calculate pre-API overhead (everything before api_request_sent)
+  const apiRequestSent = markMap.get('query_api_request_sent')
+  if (apiRequestSent !== undefined) {
+    lines.push('')
+    lines.push(
+      `  ${'Total pre-API overhead'.padEnd(22)} ${formatMs(apiRequestSent).padStart(10)}ms`,
+    )
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Log the query profile report to debug output
+ */
+export function logQueryProfileReport(): void {
+  if (!ENABLED) return
+  logForDebugging(getQueryProfileReport())
+}

package/utils/queueProcessor.ts

@@ -0,0 +1,95 @@
+import type { QueuedCommand } from '../types/textInputTypes.js'
+import {
+  dequeue,
+  dequeueAllMatching,
+  hasCommandsInQueue,
+  peek,
+} from './messageQueueManager.js'
+
+type ProcessQueueParams = {
+  executeInput: (commands: QueuedCommand[]) => Promise<void>
+}
+
+type ProcessQueueResult = {
+  processed: boolean
+}
+
+/**
+ * Check if a queued command is a slash command (value starts with '/').
+ */
+function isSlashCommand(cmd: QueuedCommand): boolean {
+  if (typeof cmd.value === 'string') {
+    return cmd.value.trim().startsWith('/')
+  }
+  // For ContentBlockParam[], check the first text block
+  for (const block of cmd.value) {
+    if (block.type === 'text') {
+      return block.text.trim().startsWith('/')
+    }
+  }
+  return false
+}
+
+/**
+ * Processes commands from the queue.
+ *
+ * Slash commands (starting with '/') and bash-mode commands are processed
+ * one at a time so each goes through the executeInput path individually.
+ * Bash commands need individual processing to preserve per-command error
+ * isolation, exit codes, and progress UI. Other non-slash commands are
+ * batched: all items **with the same mode** as the highest-priority item
+ * are drained at once and passed as a single array to executeInput — each
+ * becomes its own user message with its own UUID. Different modes
+ * (e.g. prompt vs task-notification) are never mixed because they are
+ * treated differently downstream.
+ *
+ * The caller is responsible for ensuring no query is currently running
+ * and for calling this function again after each command completes
+ * until the queue is empty.
+ *
+ * @returns result with processed status
+ */
+export function processQueueIfReady({
+  executeInput,
+}: ProcessQueueParams): ProcessQueueResult {
+  // This processor runs on the REPL main thread between turns. Skip anything
+  // addressed to a subagent — an unfiltered peek() returning a subagent
+  // notification would set targetMode, dequeueAllMatching would find nothing
+  // matching that mode with agentId===undefined, and we'd return processed:
+  // false with the queue unchanged → the React effect never re-fires and any
+  // queued user prompt stalls permanently.
+  const isMainThread = (cmd: QueuedCommand) => cmd.agentId === undefined
+
+  const next = peek(isMainThread)
+  if (!next) {
+    return { processed: false }
+  }
+
+  // Slash commands and bash-mode commands are processed individually.
+  // Bash commands need per-command error isolation, exit codes, and progress UI.
+  if (isSlashCommand(next) || next.mode === 'bash') {
+    const cmd = dequeue(isMainThread)!
+    void executeInput([cmd])
+    return { processed: true }
+  }
+
+  // Drain all non-slash-command items with the same mode at once.
+  const targetMode = next.mode
+  const commands = dequeueAllMatching(
+    cmd => isMainThread(cmd) && !isSlashCommand(cmd) && cmd.mode === targetMode,
+  )
+  if (commands.length === 0) {
+    return { processed: false }
+  }
+
+  void executeInput(commands)
+  return { processed: true }
+}
+
+/**
+ * Checks if the queue has pending commands.
+ * Use this to determine if queue processing should be triggered.
+ */
+export function hasQueuedCommands(): boolean {
+  return hasCommandsInQueue()
+}

package/utils/readEditContext.ts

@@ -0,0 +1,227 @@
+import { type FileHandle, open } from 'fs/promises'
+import { isENOENT } from './errors.js'
+
+export const CHUNK_SIZE = 8 * 1024
+export const MAX_SCAN_BYTES = 10 * 1024 * 1024
+const NL = 0x0a
+
+export type EditContext = {
+  /** Slice of the file: contextLines before/after the match, on line boundaries. */
+  content: string
+  /** 1-based line number of content's first line in the original file. */
+  lineOffset: number
+  /** True if MAX_SCAN_BYTES was hit without finding the needle. */
+  truncated: boolean
+}
+
+/**
+ * Finds `needle` in the file at `path` and returns a context-window slice
+ * containing the match plus `contextLines` of surrounding context on each side.
+ *
+ * Scans in 8KB chunks with a straddle overlap so matches crossing a chunk
+ * boundary are found. Capped at MAX_SCAN_BYTES. No stat — EOF detected via
+ * bytesRead.
+ *
+ * React callers: wrap in useState lazy-init then use() + Suspense. useMemo
+ * re-runs when callers pass fresh array literals.
+ *
+ * Returns null on ENOENT. Returns { truncated: true, content: '' } if the
+ * needle isn't found within MAX_SCAN_BYTES.
+ */
+export async function readEditContext(
+  path: string,
+  needle: string,
+  contextLines = 3,
+): Promise<EditContext | null> {
+  const handle = await openForScan(path)
+  if (handle === null) return null
+  try {
+    return await scanForContext(handle, needle, contextLines)
+  } finally {
+    await handle.close()
+  }
+}
+
+/**
+ * Opens `path` for reading. Returns null on ENOENT. Caller owns close().
+ */
+export async function openForScan(path: string): Promise<FileHandle | null> {
+  try {
+    return await open(path, 'r')
+  } catch (e) {
+    if (isENOENT(e)) return null
+    throw e
+  }
+}
+
+/**
+ * Handle-accepting core of readEditContext. Caller owns open/close.
+ */
+export async function scanForContext(
+  handle: FileHandle,
+  needle: string,
+  contextLines: number,
+): Promise<EditContext> {
+  if (needle === '') return { content: '', lineOffset: 1, truncated: false }
+  const needleLF = Buffer.from(needle, 'utf8')
+  // Model sends LF; files may be CRLF. Count newlines to size the overlap for
+  // the longer CRLF form; defer encoding the CRLF buffer until LF scan misses.
+  let nlCount = 0
+  for (let i = 0; i < needleLF.length; i++) if (needleLF[i] === NL) nlCount++
+  let needleCRLF: Buffer | undefined
+  const overlap = needleLF.length + nlCount - 1
+
+  const buf = Buffer.allocUnsafe(CHUNK_SIZE + overlap)
+  let pos = 0
+  let linesBeforePos = 0
+  let prevTail = 0
+
+  while (pos < MAX_SCAN_BYTES) {
+    const { bytesRead } = await handle.read(buf, prevTail, CHUNK_SIZE, pos)
+    if (bytesRead === 0) break
+    const viewLen = prevTail + bytesRead
+
+    let matchAt = indexOfWithin(buf, needleLF, viewLen)
+    let matchLen = needleLF.length
+    if (matchAt === -1 && nlCount > 0) {
+      needleCRLF ??= Buffer.from(needle.replaceAll('\n', '\r\n'), 'utf8')
+      matchAt = indexOfWithin(buf, needleCRLF, viewLen)
+      matchLen = needleCRLF.length
+    }
+    if (matchAt !== -1) {
+      const absMatch = pos - prevTail + matchAt
+      return await sliceContext(
+        handle,
+        buf,
+        absMatch,
+        matchLen,
+        contextLines,
+        linesBeforePos + countNewlines(buf, 0, matchAt),
+      )
+    }
+    pos += bytesRead
+    // Shift the tail to the front for straddle. linesBeforePos tracks
+    // newlines in bytes we've DISCARDED (not in buf) — count only the
+    // non-overlap portion we're about to copyWithin over.
+    const nextTail = Math.min(overlap, viewLen)
+    linesBeforePos += countNewlines(buf, 0, viewLen - nextTail)
+    prevTail = nextTail
+    buf.copyWithin(0, viewLen - prevTail, viewLen)
+  }
+
+  return { content: '', lineOffset: 1, truncated: pos >= MAX_SCAN_BYTES }
+}
+
+/**
+ * Reads the entire file via `handle` up to MAX_SCAN_BYTES. Returns null if the
+ * file exceeds the cap. For the multi-edit path in FileEditToolDiff where
+ * sequential replacements need the full string.
+ *
+ * Single buffer, doubles on fill — ~log2(size/8KB) allocs instead of O(n)
+ * chunks + concat. Reads directly into the right offset; no intermediate copies.
+ */
+export async function readCapped(handle: FileHandle): Promise<string | null> {
+  let buf = Buffer.allocUnsafe(CHUNK_SIZE)
+  let total = 0
+  for (;;) {
+    if (total === buf.length) {
+      const grown = Buffer.allocUnsafe(
+        Math.min(buf.length * 2, MAX_SCAN_BYTES + CHUNK_SIZE),
+      )
+      buf.copy(grown, 0, 0, total)
+      buf = grown
+    }
+    const { bytesRead } = await handle.read(
+      buf,
+      total,
+      buf.length - total,
+      total,
+    )
+    if (bytesRead === 0) break
+    total += bytesRead
+    if (total > MAX_SCAN_BYTES) return null
+  }
+  return normalizeCRLF(buf, total)
+}
+
+/** buf.indexOf bounded to [0, end) without allocating a view. */
+function indexOfWithin(buf: Buffer, needle: Buffer, end: number): number {
+  const at = buf.indexOf(needle)
+  return at === -1 || at + needle.length > end ? -1 : at
+}
+
+function countNewlines(buf: Buffer, start: number, end: number): number {
+  let n = 0
+  for (let i = start; i < end; i++) if (buf[i] === NL) n++
+  return n
+}
+
+/** Decode buf[0..len) to utf8, normalizing CRLF only if CR is present. */
+function normalizeCRLF(buf: Buffer, len: number): string {
+  const s = buf.toString('utf8', 0, len)
+  return s.includes('\r') ? s.replaceAll('\r\n', '\n') : s
+}
+
+/**
+ * Given an absolute match offset, read ±contextLines around it and return
+ * the decoded slice with its starting line number. Reuses `scratch` (the
+ * caller's scan buffer) for back/forward/output reads — zero new allocs
+ * when the context fits, one alloc otherwise.
+ */
+async function sliceContext(
+  handle: FileHandle,
+  scratch: Buffer,
+  matchStart: number,
+  matchLen: number,
+  contextLines: number,
+  linesBeforeMatch: number,
+): Promise<EditContext> {
+  // Scan backward from matchStart to find contextLines prior newlines.
+  const backChunk = Math.min(matchStart, CHUNK_SIZE)
+  const { bytesRead: backRead } = await handle.read(
+    scratch,
+    0,
+    backChunk,
+    matchStart - backChunk,
+  )
+  let ctxStart = matchStart
+  let nlSeen = 0
+  for (let i = backRead - 1; i >= 0 && nlSeen <= contextLines; i--) {
+    if (scratch[i] === NL) {
+      nlSeen++
+      if (nlSeen > contextLines) break
+    }
+    ctxStart--
+  }
+  // Compute lineOffset now, before scratch is overwritten by the forward read.
+  const walkedBack = matchStart - ctxStart
+  const lineOffset =
+    linesBeforeMatch -
+    countNewlines(scratch, backRead - walkedBack, backRead) +
+    1
+
+  // Scan forward from matchEnd to find contextLines trailing newlines.
+  const matchEnd = matchStart + matchLen
+  const { bytesRead: fwdRead } = await handle.read(
+    scratch,
+    0,
+    CHUNK_SIZE,
+    matchEnd,
+  )
+  let ctxEnd = matchEnd
+  nlSeen = 0
+  for (let i = 0; i < fwdRead; i++) {
+    ctxEnd++
+    if (scratch[i] === NL) {
+      nlSeen++
+      if (nlSeen >= contextLines + 1) break
+    }
+  }
+
+  // Read the exact context range. Reuse scratch if it fits.
+  const len = ctxEnd - ctxStart
+  const out = len <= scratch.length ? scratch : Buffer.allocUnsafe(len)
+  const { bytesRead: outRead } = await handle.read(out, 0, len, ctxStart)
+
+  return { content: normalizeCRLF(out, outRead), lineOffset, truncated: false }
+}