@xortex/xcode 3.0.0

package/utils/sliceAnsi.ts

@@ -0,0 +1,91 @@
+import {
+  type AnsiCode,
+  ansiCodesToString,
+  reduceAnsiCodes,
+  tokenize,
+  undoAnsiCodes,
+} from '@alcalzone/ansi-tokenize'
+import { stringWidth } from '../ink/stringWidth.js'
+
+// A code is an "end code" if its code equals its endCode (e.g., hyperlink close)
+function isEndCode(code: AnsiCode): boolean {
+  return code.code === code.endCode
+}
+
+// Filter to only include "start codes" (not end codes)
+function filterStartCodes(codes: AnsiCode[]): AnsiCode[] {
+  return codes.filter(c => !isEndCode(c))
+}
+
+/**
+ * Slice a string containing ANSI escape codes.
+ *
+ * Unlike the slice-ansi package, this properly handles OSC 8 hyperlink
+ * sequences because @alcalzone/ansi-tokenize tokenizes them correctly.
+ */
+export default function sliceAnsi(
+  str: string,
+  start: number,
+  end?: number,
+): string {
+  // Don't pass `end` to tokenize — it counts code units, not display cells,
+  // so it drops tokens early for text with zero-width combining marks.
+  const tokens = tokenize(str)
+  let activeCodes: AnsiCode[] = []
+  let position = 0
+  let result = ''
+  let include = false
+
+  for (const token of tokens) {
+    // Advance by display width, not code units. Combining marks (Devanagari
+    // matras, virama, diacritics) are width 0 — counting them via .length
+    // advanced position past `end` early and truncated the slice. Callers
+    // pass start/end in display cells (via stringWidth), so position must
+    // track the same units.
+    const width =
+      token.type === 'ansi' ? 0 : token.fullWidth ? 2 : stringWidth(token.value)
+
+    // Break AFTER trailing zero-width marks — a combining mark attaches to
+    // the preceding base char, so "भा" (भ + ा, 1 display cell) sliced at
+    // end=1 must include the ा. Breaking on position >= end BEFORE the
+    // zero-width check would drop it and render भ bare. ANSI codes are
+    // width 0 but must NOT be included past end (they open new style runs
+    // that leak into the undo sequence), so gate on char type too. The
+    // !include guard ensures empty slices (start===end) stay empty even
+    // when the string starts with a zero-width char (BOM, ZWJ).
+    if (end !== undefined && position >= end) {
+      if (token.type === 'ansi' || width > 0 || !include) break
+    }
+
+    if (token.type === 'ansi') {
+      activeCodes.push(token)
+      if (include) {
+        // Emit all ANSI codes during the slice
+        result += token.code
+      }
+    } else {
+      if (!include && position >= start) {
+        // Skip leading zero-width marks at the start boundary — they belong
+        // to the preceding base char in the left half. Without this, the
+        // mark appears in BOTH halves: left+right ≠ original. Only applies
+        // when start > 0 (otherwise there's no preceding char to own it).
+        if (start > 0 && width === 0) continue
+        include = true
+        // Reduce and filter to only active start codes
+        activeCodes = filterStartCodes(reduceAnsiCodes(activeCodes))
+        result = ansiCodesToString(activeCodes)
+      }
+
+      if (include) {
+        result += token.value
+      }
+
+      position += width
+    }
+  }
+
+  // Only undo start codes that are still active
+  const activeStartCodes = filterStartCodes(reduceAnsiCodes(activeCodes))
+  result += ansiCodesToString(undoAnsiCodes(activeStartCodes))
+  return result
+}

package/utils/slowOperations.ts

@@ -0,0 +1,286 @@
+import { feature } from 'bun:bundle'
+import type { WriteFileOptions } from 'fs'
+import {
+  closeSync,
+  writeFileSync as fsWriteFileSync,
+  fsyncSync,
+  openSync,
+} from 'fs'
+// biome-ignore lint: This file IS the cloneDeep wrapper - it must import the original
+import lodashCloneDeep from 'lodash-es/cloneDeep.js'
+import { addSlowOperation } from '../bootstrap/state.js'
+import { logForDebugging } from './debug.js'
+
+// Extended WriteFileOptions to include 'flush' which is available in Node.js 20.1.0+
+// but not yet in @types/node
+type WriteFileOptionsWithFlush =
+  | WriteFileOptions
+  | (WriteFileOptions & { flush?: boolean })
+
+// --- Slow operation logging infrastructure ---
+
+/**
+ * Threshold in milliseconds for logging slow JSON/clone operations.
+ * Operations taking longer than this will be logged for debugging.
+ * - Override: set CLAUDE_CODE_SLOW_OPERATION_THRESHOLD_MS to a number
+ * - Dev builds: 20ms (lower threshold for development)
+ * - Ants: 300ms (enabled for all internal users)
+ */
+const SLOW_OPERATION_THRESHOLD_MS = (() => {
+  const envValue = process.env.CLAUDE_CODE_SLOW_OPERATION_THRESHOLD_MS
+  if (envValue !== undefined) {
+    const parsed = Number(envValue)
+    if (!Number.isNaN(parsed) && parsed >= 0) {
+      return parsed
+    }
+  }
+  if (process.env.NODE_ENV === 'development') {
+    return 20
+  }
+  if (process.env.USER_TYPE === 'ant') {
+    return 300
+  }
+  return Infinity
+})()
+
+// Re-export for callers that still need the threshold value directly
+export { SLOW_OPERATION_THRESHOLD_MS }
+
+// Module-level re-entrancy guard. logForDebugging writes to a debug file via
+// appendFileSync, which goes through slowLogging again. Without this guard,
+// a slow appendFileSync → dispose → logForDebugging → appendFileSync → dispose → ...
+let isLogging = false
+
+/**
+ * Extract the first stack frame outside this file, so the DevBar warning
+ * points at the actual caller instead of a useless `Object{N keys}`.
+ * Only called when an operation was actually slow — never on the fast path.
+ */
+export function callerFrame(stack: string | undefined): string {
+  if (!stack) return ''
+  for (const line of stack.split('\n')) {
+    if (line.includes('slowOperations')) continue
+    const m = line.match(/([^/\\]+?):(\d+):\d+\)?$/)
+    if (m) return ` @ ${m[1]}:${m[2]}`
+  }
+  return ''
+}
+
+/**
+ * Builds a human-readable description from tagged template arguments.
+ * Only called when an operation was actually slow — never on the fast path.
+ *
+ * args[0] = TemplateStringsArray, args[1..n] = interpolated values
+ */
+function buildDescription(args: IArguments): string {
+  const strings = args[0] as TemplateStringsArray
+  let result = ''
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i]
+    if (i + 1 < args.length) {
+      const v = args[i + 1]
+      if (Array.isArray(v)) {
+        result += `Array[${(v as unknown[]).length}]`
+      } else if (v !== null && typeof v === 'object') {
+        result += `Object{${Object.keys(v as Record<string, unknown>).length} keys}`
+      } else if (typeof v === 'string') {
+        result += v.length > 80 ? `${v.slice(0, 80)}…` : v
+      } else {
+        result += String(v)
+      }
+    }
+  }
+  return result
+}
+
+class AntSlowLogger {
+  startTime: number
+  args: IArguments
+  err: Error
+
+  constructor(args: IArguments) {
+    this.startTime = performance.now()
+    this.args = args
+    // V8/JSC capture the stack at construction but defer the expensive string
+    // formatting until .stack is read — so this stays off the fast path.
+    this.err = new Error()
+  }
+
+  [Symbol.dispose](): void {
+    const duration = performance.now() - this.startTime
+    if (duration > SLOW_OPERATION_THRESHOLD_MS && !isLogging) {
+      isLogging = true
+      try {
+        const description =
+          buildDescription(this.args) + callerFrame(this.err.stack)
+        logForDebugging(
+          `[SLOW OPERATION DETECTED] ${description} (${duration.toFixed(1)}ms)`,
+        )
+        addSlowOperation(description, duration)
+      } finally {
+        isLogging = false
+      }
+    }
+  }
+}
+
+const NOOP_LOGGER: Disposable = { [Symbol.dispose]() {} }
+
+// Must be regular functions (not arrows) to access `arguments`
+function slowLoggingAnt(
+  _strings: TemplateStringsArray,
+  ..._values: unknown[]
+): AntSlowLogger {
+  // eslint-disable-next-line prefer-rest-params
+  return new AntSlowLogger(arguments)
+}
+
+function slowLoggingExternal(): Disposable {
+  return NOOP_LOGGER
+}
+
+/**
+ * Tagged template for slow operation logging.
+ *
+ * In ANT builds: creates an AntSlowLogger that times the operation and logs
+ * if it exceeds the threshold. Description is built lazily only when slow.
+ *
+ * In external builds: returns a singleton no-op disposable. Zero allocations,
+ * zero timing. AntSlowLogger and buildDescription are dead-code-eliminated.
+ *
+ * @example
+ * using _ = slowLogging`structuredClone(${value})`
+ * const result = structuredClone(value)
+ */
+export const slowLogging: {
+  (strings: TemplateStringsArray, ...values: unknown[]): Disposable
+} = feature('SLOW_OPERATION_LOGGING') ? slowLoggingAnt : slowLoggingExternal
+
+// --- Wrapped operations ---
+
+/**
+ * Wrapped JSON.stringify with slow operation logging.
+ * Use this instead of JSON.stringify directly to detect performance issues.
+ *
+ * @example
+ * import { jsonStringify } from './slowOperations.js'
+ * const json = jsonStringify(data)
+ * const prettyJson = jsonStringify(data, null, 2)
+ */
+export function jsonStringify(
+  value: unknown,
+  replacer?: (this: unknown, key: string, value: unknown) => unknown,
+  space?: string | number,
+): string
+export function jsonStringify(
+  value: unknown,
+  replacer?: (number | string)[] | null,
+  space?: string | number,
+): string
+export function jsonStringify(
+  value: unknown,
+  replacer?:
+    | ((this: unknown, key: string, value: unknown) => unknown)
+    | (number | string)[]
+    | null,
+  space?: string | number,
+): string {
+  using _ = slowLogging`JSON.stringify(${value})`
+  return JSON.stringify(
+    value,
+    replacer as Parameters<typeof JSON.stringify>[1],
+    space,
+  )
+}
+
+/**
+ * Wrapped JSON.parse with slow operation logging.
+ * Use this instead of JSON.parse directly to detect performance issues.
+ *
+ * @example
+ * import { jsonParse } from './slowOperations.js'
+ * const data = jsonParse(jsonString)
+ */
+export const jsonParse: typeof JSON.parse = (text, reviver) => {
+  using _ = slowLogging`JSON.parse(${text})`
+  // V8 de-opts JSON.parse when a second argument is passed, even if undefined.
+  // Branch explicitly so the common (no-reviver) path stays on the fast path.
+  return typeof reviver === 'undefined'
+    ? JSON.parse(text)
+    : JSON.parse(text, reviver)
+}
+
+/**
+ * Wrapped structuredClone with slow operation logging.
+ * Use this instead of structuredClone directly to detect performance issues.
+ *
+ * @example
+ * import { clone } from './slowOperations.js'
+ * const copy = clone(originalObject)
+ */
+export function clone<T>(value: T, options?: StructuredSerializeOptions): T {
+  using _ = slowLogging`structuredClone(${value})`
+  return structuredClone(value, options)
+}
+
+/**
+ * Wrapped cloneDeep with slow operation logging.
+ * Use this instead of lodash cloneDeep directly to detect performance issues.
+ *
+ * @example
+ * import { cloneDeep } from './slowOperations.js'
+ * const copy = cloneDeep(originalObject)
+ */
+export function cloneDeep<T>(value: T): T {
+  using _ = slowLogging`cloneDeep(${value})`
+  return lodashCloneDeep(value)
+}
+
+/**
+ * Wrapper around fs.writeFileSync with slow operation logging.
+ * Supports flush option to ensure data is written to disk before returning.
+ * @param filePath The path to the file to write to
+ * @param data The data to write (string or Buffer)
+ * @param options Optional write options (encoding, mode, flag, flush)
+ * @deprecated Use `fs.promises.writeFile` instead for non-blocking writes.
+ * Sync file writes block the event loop and cause performance issues.
+ */
+export function writeFileSync_DEPRECATED(
+  filePath: string,
+  data: string | NodeJS.ArrayBufferView,
+  options?: WriteFileOptionsWithFlush,
+): void {
+  using _ = slowLogging`fs.writeFileSync(${filePath}, ${data})`
+
+  // Check if flush is requested (for object-style options)
+  const needsFlush =
+    options !== null &&
+    typeof options === 'object' &&
+    'flush' in options &&
+    options.flush === true
+
+  if (needsFlush) {
+    // Manual flush: open file, write, fsync, close
+    const encoding =
+      typeof options === 'object' && 'encoding' in options
+        ? options.encoding
+        : undefined
+    const mode =
+      typeof options === 'object' && 'mode' in options
+        ? options.mode
+        : undefined
+    let fd: number | undefined
+    try {
+      fd = openSync(filePath, 'w', mode)
+      fsWriteFileSync(fd, data, { encoding: encoding ?? undefined })
+      fsyncSync(fd)
+    } finally {
+      if (fd !== undefined) {
+        closeSync(fd)
+      }
+    }
+  } else {
+    // No flush needed, use standard writeFileSync
+    fsWriteFileSync(filePath, data, options as WriteFileOptions)
+  }
+}

package/utils/standaloneAgent.ts

@@ -0,0 +1,23 @@
+/**
+ * Standalone agent utilities for sessions with custom names/colors
+ *
+ * These helpers provide access to standalone agent context (name and color)
+ * for sessions that are NOT part of a swarm team. When a session is part
+ * of a swarm, these functions return undefined to let swarm context take
+ * precedence.
+ */
+
+import type { AppState } from '../state/AppState.js'
+import { getTeamName } from './teammate.js'
+
+/**
+ * Returns the standalone agent name if set and not a swarm teammate.
+ * Uses getTeamName() for consistency with isTeammate() swarm detection.
+ */
+export function getStandaloneAgentName(appState: AppState): string | undefined {
+  // If in a team (swarm), don't return standalone name
+  if (getTeamName()) {
+    return undefined
+  }
+  return appState.standaloneAgentContext?.name
+}

package/utils/startupProfiler.ts

@@ -0,0 +1,194 @@
+/**
+ * Startup profiling utility for measuring and reporting time spent in various
+ * initialization phases.
+ *
+ * Two modes:
+ * 1. Sampled logging: 100% of ant users, 0.1% of external users - logs phases to Statsig
+ * 2. Detailed profiling: CLAUDE_CODE_PROFILE_STARTUP=1 - full report with memory snapshots
+ *
+ * Uses Node.js built-in performance hooks API for standard timing measurement.
+ */
+
+import { dirname, join } from 'path'
+import { getSessionId } from 'src/bootstrap/state.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../services/analytics/index.js'
+import { logForDebugging } from './debug.js'
+import { getClaudeConfigHomeDir, isEnvTruthy } from './envUtils.js'
+import { getFsImplementation } from './fsOperations.js'
+import { formatMs, formatTimelineLine, getPerformance } from './profilerBase.js'
+import { writeFileSync_DEPRECATED } from './slowOperations.js'
+
+// Module-level state - decided once at module load
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const DETAILED_PROFILING = isEnvTruthy(process.env.CLAUDE_CODE_PROFILE_STARTUP)
+
+// Sampling for Statsig logging: 100% ant, 0.5% external
+// Decision made once at startup - non-sampled users pay no profiling cost
+const STATSIG_SAMPLE_RATE = 0.005
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const STATSIG_LOGGING_SAMPLED =
+  process.env.USER_TYPE === 'ant' || Math.random() < STATSIG_SAMPLE_RATE
+
+// Enable profiling if either detailed mode OR sampled for Statsig
+const SHOULD_PROFILE = DETAILED_PROFILING || STATSIG_LOGGING_SAMPLED
+
+// Track memory snapshots separately (perf_hooks doesn't track memory).
+// Only used when DETAILED_PROFILING is enabled.
+// Stored as an array that appends in the same order as perf.mark() calls, so
+// memorySnapshots[i] corresponds to getEntriesByType('mark')[i]. Using a Map
+// keyed by checkpoint name is wrong because some checkpoints fire more than
+// once (e.g. loadSettingsFromDisk_start fires during init and again after
+// plugins reset the settings cache), and the second call would overwrite the
+// first's memory snapshot.
+const memorySnapshots: NodeJS.MemoryUsage[] = []
+
+// Phase definitions for Statsig logging: [startCheckpoint, endCheckpoint]
+const PHASE_DEFINITIONS = {
+  import_time: ['cli_entry', 'main_tsx_imports_loaded'],
+  init_time: ['init_function_start', 'init_function_end'],
+  settings_time: ['eagerLoadSettings_start', 'eagerLoadSettings_end'],
+  total_time: ['cli_entry', 'main_after_run'],
+} as const
+
+// Record initial checkpoint if profiling is enabled
+if (SHOULD_PROFILE) {
+  // eslint-disable-next-line custom-rules/no-top-level-side-effects
+  profileCheckpoint('profiler_initialized')
+}
+
+/**
+ * Record a checkpoint with the given name
+ */
+export function profileCheckpoint(name: string): void {
+  if (!SHOULD_PROFILE) return
+
+  const perf = getPerformance()
+  perf.mark(name)
+
+  // Only capture memory when detailed profiling enabled (env var)
+  if (DETAILED_PROFILING) {
+    memorySnapshots.push(process.memoryUsage())
+  }
+}
+
+/**
+ * Get a formatted report of all checkpoints
+ * Only available when DETAILED_PROFILING is enabled
+ */
+function getReport(): string {
+  if (!DETAILED_PROFILING) {
+    return 'Startup profiling not enabled'
+  }
+
+  const perf = getPerformance()
+  const marks = perf.getEntriesByType('mark')
+  if (marks.length === 0) {
+    return 'No profiling checkpoints recorded'
+  }
+
+  const lines: string[] = []
+  lines.push('='.repeat(80))
+  lines.push('STARTUP PROFILING REPORT')
+  lines.push('='.repeat(80))
+  lines.push('')
+
+  let prevTime = 0
+  for (const [i, mark] of marks.entries()) {
+    lines.push(
+      formatTimelineLine(
+        mark.startTime,
+        mark.startTime - prevTime,
+        mark.name,
+        memorySnapshots[i],
+        8,
+        7,
+      ),
+    )
+    prevTime = mark.startTime
+  }
+
+  const lastMark = marks[marks.length - 1]
+  lines.push('')
+  lines.push(`Total startup time: ${formatMs(lastMark?.startTime ?? 0)}ms`)
+  lines.push('='.repeat(80))
+
+  return lines.join('\n')
+}
+
+let reported = false
+
+export function profileReport(): void {
+  if (reported) return
+  reported = true
+
+  // Log to Statsig (sampled: 100% ant, 0.1% external)
+  logStartupPerf()
+
+  // Output detailed report if CLAUDE_CODE_PROFILE_STARTUP=1
+  if (DETAILED_PROFILING) {
+    // Write to file
+    const path = getStartupPerfLogPath()
+    const dir = dirname(path)
+    const fs = getFsImplementation()
+    fs.mkdirSync(dir)
+    writeFileSync_DEPRECATED(path, getReport(), {
+      encoding: 'utf8',
+      flush: true,
+    })
+
+    logForDebugging('Startup profiling report:')
+    logForDebugging(getReport())
+  }
+}
+
+export function isDetailedProfilingEnabled(): boolean {
+  return DETAILED_PROFILING
+}
+
+export function getStartupPerfLogPath(): string {
+  return join(getClaudeConfigHomeDir(), 'startup-perf', `${getSessionId()}.txt`)
+}
+
+/**
+ * Log startup performance phases to Statsig.
+ * Only logs if this session was sampled at startup.
+ */
+export function logStartupPerf(): void {
+  // Only log if we were sampled (decision made at module load)
+  if (!STATSIG_LOGGING_SAMPLED) return
+
+  const perf = getPerformance()
+  const marks = perf.getEntriesByType('mark')
+  if (marks.length === 0) return
+
+  // Build checkpoint lookup
+  const checkpointTimes = new Map<string, number>()
+  for (const mark of marks) {
+    checkpointTimes.set(mark.name, mark.startTime)
+  }
+
+  // Compute phase durations
+  const metadata: Record<string, number | undefined> = {}
+
+  for (const [phaseName, [startCheckpoint, endCheckpoint]] of Object.entries(
+    PHASE_DEFINITIONS,
+  )) {
+    const startTime = checkpointTimes.get(startCheckpoint)
+    const endTime = checkpointTimes.get(endCheckpoint)
+
+    if (startTime !== undefined && endTime !== undefined) {
+      metadata[`${phaseName}_ms`] = Math.round(endTime - startTime)
+    }
+  }
+
+  // Add checkpoint count for debugging
+  metadata.checkpoint_count = marks.length
+
+  logEvent(
+    'tengu_startup_perf',
+    metadata as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  )
+}