@xortex/xcode 3.0.0

package/utils/imageStore.ts

@@ -0,0 +1,167 @@
+import { mkdir, open } from 'fs/promises'
+import { join } from 'path'
+import { getSessionId } from '../bootstrap/state.js'
+import type { PastedContent } from './config.js'
+import { logForDebugging } from './debug.js'
+import { getClaudeConfigHomeDir } from './envUtils.js'
+import { getFsImplementation } from './fsOperations.js'
+
+const IMAGE_STORE_DIR = 'image-cache'
+const MAX_STORED_IMAGE_PATHS = 200
+
+// In-memory cache of stored image paths
+const storedImagePaths = new Map<number, string>()
+
+/**
+ * Get the image store directory for the current session.
+ */
+function getImageStoreDir(): string {
+  return join(getClaudeConfigHomeDir(), IMAGE_STORE_DIR, getSessionId())
+}
+
+/**
+ * Ensure the image store directory exists.
+ */
+async function ensureImageStoreDir(): Promise<void> {
+  const dir = getImageStoreDir()
+  await mkdir(dir, { recursive: true })
+}
+
+/**
+ * Get the file path for an image by ID.
+ */
+function getImagePath(imageId: number, mediaType: string): string {
+  const extension = mediaType.split('/')[1] || 'png'
+  return join(getImageStoreDir(), `${imageId}.${extension}`)
+}
+
+/**
+ * Cache the image path immediately (fast, no file I/O).
+ */
+export function cacheImagePath(content: PastedContent): string | null {
+  if (content.type !== 'image') {
+    return null
+  }
+  const imagePath = getImagePath(content.id, content.mediaType || 'image/png')
+  evictOldestIfAtCap()
+  storedImagePaths.set(content.id, imagePath)
+  return imagePath
+}
+
+/**
+ * Store an image from pastedContents to disk.
+ */
+export async function storeImage(
+  content: PastedContent,
+): Promise<string | null> {
+  if (content.type !== 'image') {
+    return null
+  }
+
+  try {
+    await ensureImageStoreDir()
+    const imagePath = getImagePath(content.id, content.mediaType || 'image/png')
+    const fh = await open(imagePath, 'w', 0o600)
+    try {
+      await fh.writeFile(content.content, { encoding: 'base64' })
+      await fh.datasync()
+    } finally {
+      await fh.close()
+    }
+    evictOldestIfAtCap()
+    storedImagePaths.set(content.id, imagePath)
+    logForDebugging(`Stored image ${content.id} to ${imagePath}`)
+    return imagePath
+  } catch (error) {
+    logForDebugging(`Failed to store image: ${error}`)
+    return null
+  }
+}
+
+/**
+ * Store all images from pastedContents to disk.
+ */
+export async function storeImages(
+  pastedContents: Record<number, PastedContent>,
+): Promise<Map<number, string>> {
+  const pathMap = new Map<number, string>()
+
+  for (const [id, content] of Object.entries(pastedContents)) {
+    if (content.type === 'image') {
+      const path = await storeImage(content)
+      if (path) {
+        pathMap.set(Number(id), path)
+      }
+    }
+  }
+
+  return pathMap
+}
+
+/**
+ * Get the file path for a stored image by ID.
+ */
+export function getStoredImagePath(imageId: number): string | null {
+  return storedImagePaths.get(imageId) ?? null
+}
+
+/**
+ * Clear the in-memory cache of stored image paths.
+ */
+export function clearStoredImagePaths(): void {
+  storedImagePaths.clear()
+}
+
+function evictOldestIfAtCap(): void {
+  while (storedImagePaths.size >= MAX_STORED_IMAGE_PATHS) {
+    const oldest = storedImagePaths.keys().next().value
+    if (oldest !== undefined) {
+      storedImagePaths.delete(oldest)
+    } else {
+      break
+    }
+  }
+}
+
+/**
+ * Clean up old image cache directories from previous sessions.
+ */
+export async function cleanupOldImageCaches(): Promise<void> {
+  const fsImpl = getFsImplementation()
+  const baseDir = join(getClaudeConfigHomeDir(), IMAGE_STORE_DIR)
+  const currentSessionId = getSessionId()
+
+  try {
+    let sessionDirs
+    try {
+      sessionDirs = await fsImpl.readdir(baseDir)
+    } catch {
+      return
+    }
+
+    for (const sessionDir of sessionDirs) {
+      if (sessionDir.name === currentSessionId) {
+        continue
+      }
+
+      const sessionPath = join(baseDir, sessionDir.name)
+      try {
+        await fsImpl.rm(sessionPath, { recursive: true, force: true })
+        logForDebugging(`Cleaned up old image cache: ${sessionPath}`)
+      } catch {
+        // Ignore errors for individual directories
+      }
+    }
+
+    try {
+      const remaining = await fsImpl.readdir(baseDir)
+      if (remaining.length === 0) {
+        await fsImpl.rmdir(baseDir)
+      }
+    } catch {
+      // Ignore
+    }
+  } catch {
+    // Ignore errors reading base directory
+  }
+}

package/utils/imageValidation.ts

@@ -0,0 +1,104 @@
+import { API_IMAGE_MAX_BASE64_SIZE } from '../constants/apiLimits.js'
+import { logEvent } from '../services/analytics/index.js'
+import { formatFileSize } from './format.js'
+
+/**
+ * Information about an oversized image.
+ */
+export type OversizedImage = {
+  index: number
+  size: number
+}
+
+/**
+ * Error thrown when one or more images exceed the API size limit.
+ */
+export class ImageSizeError extends Error {
+  constructor(oversizedImages: OversizedImage[], maxSize: number) {
+    let message: string
+    const firstImage = oversizedImages[0]
+    if (oversizedImages.length === 1 && firstImage) {
+      message =
+        `Image base64 size (${formatFileSize(firstImage.size)}) exceeds API limit (${formatFileSize(maxSize)}). ` +
+        `Please resize the image before sending.`
+    } else {
+      message =
+        `${oversizedImages.length} images exceed the API limit (${formatFileSize(maxSize)}): ` +
+        oversizedImages
+          .map(img => `Image ${img.index}: ${formatFileSize(img.size)}`)
+          .join(', ') +
+        `. Please resize these images before sending.`
+    }
+    super(message)
+    this.name = 'ImageSizeError'
+  }
+}
+
+/**
+ * Type guard to check if a block is a base64 image block
+ */
+function isBase64ImageBlock(
+  block: unknown,
+): block is { type: 'image'; source: { type: 'base64'; data: string } } {
+  if (typeof block !== 'object' || block === null) return false
+  const b = block as Record<string, unknown>
+  if (b.type !== 'image') return false
+  if (typeof b.source !== 'object' || b.source === null) return false
+  const source = b.source as Record<string, unknown>
+  return source.type === 'base64' && typeof source.data === 'string'
+}
+
+/**
+ * Validates that all images in messages are within the API size limit.
+ * This is a safety net at the API boundary to catch any oversized images
+ * that may have slipped through upstream processing.
+ *
+ * Note: The API's 5MB limit applies to the base64-encoded string length,
+ * not the decoded raw bytes.
+ *
+ * Works with both UserMessage/AssistantMessage types (which have { type, message })
+ * and raw MessageParam types (which have { role, content }).
+ *
+ * @param messages - Array of messages to validate
+ * @throws ImageSizeError if any image exceeds the API limit
+ */
+export function validateImagesForAPI(messages: unknown[]): void {
+  const oversizedImages: OversizedImage[] = []
+  let imageIndex = 0
+
+  for (const msg of messages) {
+    if (typeof msg !== 'object' || msg === null) continue
+
+    const m = msg as Record<string, unknown>
+
+    // Handle wrapped message format { type: 'user', message: { role, content } }
+    // Only check user messages
+    if (m.type !== 'user') continue
+
+    const innerMessage = m.message as Record<string, unknown> | undefined
+    if (!innerMessage) continue
+
+    const content = innerMessage.content
+    if (typeof content === 'string' || !Array.isArray(content)) continue
+
+    for (const block of content) {
+      if (isBase64ImageBlock(block)) {
+        imageIndex++
+        // Check the base64-encoded string length directly (not decoded bytes)
+        // The API limit applies to the base64 payload size
+        const base64Size = block.source.data.length
+        if (base64Size > API_IMAGE_MAX_BASE64_SIZE) {
+          logEvent('tengu_image_api_validation_failed', {
+            base64_size_bytes: base64Size,
+            max_bytes: API_IMAGE_MAX_BASE64_SIZE,
+          })
+          oversizedImages.push({ index: imageIndex, size: base64Size })
+        }
+      }
+    }
+  }
+
+  if (oversizedImages.length > 0) {
+    throw new ImageSizeError(oversizedImages, API_IMAGE_MAX_BASE64_SIZE)
+  }
+}

package/utils/immediateCommand.ts

@@ -0,0 +1,15 @@
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
+
+/**
+ * Whether inference-config commands (/model, /fast, /effort) should execute
+ * immediately (during a running query) rather than waiting for the current
+ * turn to finish.
+ *
+ * Always enabled for ants; gated by experiment for external users.
+ */
+export function shouldInferenceConfigCommandBeImmediate(): boolean {
+  return (
+    process.env.USER_TYPE === 'ant' ||
+    getFeatureValue_CACHED_MAY_BE_STALE('tengu_immediate_model_command', false)
+  )
+}

package/utils/inProcessTeammateHelpers.ts

@@ -0,0 +1,102 @@
+/**
+ * In-Process Teammate Helpers
+ *
+ * Helper functions for in-process teammate integration.
+ * Provides utilities to:
+ * - Find task ID by agent name
+ * - Handle plan approval responses
+ * - Update awaitingPlanApproval state
+ * - Detect permission-related messages
+ */
+
+import type { AppState } from '../state/AppState.js'
+import {
+  type InProcessTeammateTaskState,
+  isInProcessTeammateTask,
+} from '../tasks/InProcessTeammateTask/types.js'
+import { updateTaskState } from './task/framework.js'
+import {
+  isPermissionResponse,
+  isSandboxPermissionResponse,
+  type PlanApprovalResponseMessage,
+} from './teammateMailbox.js'
+
+type SetAppState = (updater: (prev: AppState) => AppState) => void
+
+/**
+ * Find the task ID for an in-process teammate by agent name.
+ *
+ * @param agentName - The agent name (e.g., "researcher")
+ * @param appState - Current AppState
+ * @returns Task ID if found, undefined otherwise
+ */
+export function findInProcessTeammateTaskId(
+  agentName: string,
+  appState: AppState,
+): string | undefined {
+  for (const task of Object.values(appState.tasks)) {
+    if (
+      isInProcessTeammateTask(task) &&
+      task.identity.agentName === agentName
+    ) {
+      return task.id
+    }
+  }
+  return undefined
+}
+
+/**
+ * Set awaitingPlanApproval state for an in-process teammate.
+ *
+ * @param taskId - Task ID of the in-process teammate
+ * @param setAppState - AppState setter
+ * @param awaiting - Whether teammate is awaiting plan approval
+ */
+export function setAwaitingPlanApproval(
+  taskId: string,
+  setAppState: SetAppState,
+  awaiting: boolean,
+): void {
+  updateTaskState<InProcessTeammateTaskState>(taskId, setAppState, task => ({
+    ...task,
+    awaitingPlanApproval: awaiting,
+  }))
+}
+
+/**
+ * Handle plan approval response for an in-process teammate.
+ * Called by the message callback when a plan_approval_response arrives.
+ *
+ * This resets awaitingPlanApproval to false. The permissionMode from the
+ * response is handled separately by the agent loop (Task #11).
+ *
+ * @param taskId - Task ID of the in-process teammate
+ * @param _response - The plan approval response message (for future use)
+ * @param setAppState - AppState setter
+ */
+export function handlePlanApprovalResponse(
+  taskId: string,
+  _response: PlanApprovalResponseMessage,
+  setAppState: SetAppState,
+): void {
+  setAwaitingPlanApproval(taskId, setAppState, false)
+}
+
+// ============ Permission Delegation Helpers ============
+
+/**
+ * Check if a message is a permission-related response.
+ * Used by in-process teammate message handlers to detect and process
+ * permission responses from the team leader.
+ *
+ * Handles both tool permissions and sandbox (network host) permissions.
+ *
+ * @param messageText - The raw message text to check
+ * @returns true if the message is a permission response
+ */
+export function isPermissionRelatedResponse(messageText: string): boolean {
+  return (
+    !!isPermissionResponse(messageText) ||
+    !!isSandboxPermissionResponse(messageText)
+  )
+}

package/utils/ink.ts

@@ -0,0 +1,26 @@
+import type { TextProps } from '../ink.js'
+import {
+  AGENT_COLOR_TO_THEME_COLOR,
+  type AgentColorName,
+} from '../tools/AgentTool/agentColorManager.js'
+
+const DEFAULT_AGENT_THEME_COLOR = 'cyan_FOR_SUBAGENTS_ONLY'
+
+/**
+ * Convert a color string to Ink's TextProps['color'] format.
+ * Colors are typically AgentColorName values like 'blue', 'green', etc.
+ * This converts them to theme keys so they respect the current theme.
+ * Falls back to the raw ANSI color if the color is not a known agent color.
+ */
+export function toInkColor(color: string | undefined): TextProps['color'] {
+  if (!color) {
+    return DEFAULT_AGENT_THEME_COLOR
+  }
+  // Try to map to a theme color if it's a known agent color
+  const themeColor = AGENT_COLOR_TO_THEME_COLOR[color as AgentColorName]
+  if (themeColor) {
+    return themeColor
+  }
+  // Fall back to raw ANSI color for unknown colors
+  return `ansi:${color}` as TextProps['color']
+}

package/utils/intl.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared Intl object instances with lazy initialization.
+ *
+ * Intl constructors are expensive (~0.05-0.1ms each), so we cache instances
+ * for reuse across the codebase instead of creating new ones each time.
+ * Lazy initialization ensures we only pay the cost when actually needed.
+ */
+
+// Segmenters for Unicode text processing (lazily initialized)
+let graphemeSegmenter: Intl.Segmenter | null = null
+let wordSegmenter: Intl.Segmenter | null = null
+
+export function getGraphemeSegmenter(): Intl.Segmenter {
+  if (!graphemeSegmenter) {
+    graphemeSegmenter = new Intl.Segmenter(undefined, {
+      granularity: 'grapheme',
+    })
+  }
+  return graphemeSegmenter
+}
+
+/**
+ * Extract the first grapheme cluster from a string.
+ * Returns '' for empty strings.
+ */
+export function firstGrapheme(text: string): string {
+  if (!text) return ''
+  const segments = getGraphemeSegmenter().segment(text)
+  const first = segments[Symbol.iterator]().next().value
+  return first?.segment ?? ''
+}
+
+/**
+ * Extract the last grapheme cluster from a string.
+ * Returns '' for empty strings.
+ */
+export function lastGrapheme(text: string): string {
+  if (!text) return ''
+  let last = ''
+  for (const { segment } of getGraphemeSegmenter().segment(text)) {
+    last = segment
+  }
+  return last
+}
+
+export function getWordSegmenter(): Intl.Segmenter {
+  if (!wordSegmenter) {
+    wordSegmenter = new Intl.Segmenter(undefined, { granularity: 'word' })
+  }
+  return wordSegmenter
+}
+
+// RelativeTimeFormat cache (keyed by style:numeric)
+const rtfCache = new Map<string, Intl.RelativeTimeFormat>()
+
+export function getRelativeTimeFormat(
+  style: 'long' | 'short' | 'narrow',
+  numeric: 'always' | 'auto',
+): Intl.RelativeTimeFormat {
+  const key = `${style}:${numeric}`
+  let rtf = rtfCache.get(key)
+  if (!rtf) {
+    rtf = new Intl.RelativeTimeFormat('en', { style, numeric })
+    rtfCache.set(key, rtf)
+  }
+  return rtf
+}
+
+// Timezone is constant for the process lifetime
+let cachedTimeZone: string | null = null
+
+export function getTimeZone(): string {
+  if (!cachedTimeZone) {
+    cachedTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
+  }
+  return cachedTimeZone
+}
+
+// System locale language subtag (e.g. 'en', 'ja') is constant for the process
+// lifetime. null = not yet computed; undefined = computed but unavailable (so
+// a stripped-ICU environment fails once instead of retrying on every call).
+let cachedSystemLocaleLanguage: string | undefined | null = null
+
+export function getSystemLocaleLanguage(): string | undefined {
+  if (cachedSystemLocaleLanguage === null) {
+    try {
+      const locale = Intl.DateTimeFormat().resolvedOptions().locale
+      cachedSystemLocaleLanguage = new Intl.Locale(locale).language
+    } catch {
+      cachedSystemLocaleLanguage = undefined
+    }
+  }
+  return cachedSystemLocaleLanguage
+}

package/utils/jetbrains.ts

@@ -0,0 +1,191 @@
+import { homedir, platform } from 'os'
+import { join } from 'path'
+import { getFsImplementation } from '../utils/fsOperations.js'
+import type { IdeType } from './ide.js'
+
+const PLUGIN_PREFIX = 'claude-code-jetbrains-plugin'
+
+// Map of IDE names to their directory patterns
+const ideNameToDirMap: { [key: string]: string[] } = {
+  pycharm: ['PyCharm'],
+  intellij: ['IntelliJIdea', 'IdeaIC'],
+  webstorm: ['WebStorm'],
+  phpstorm: ['PhpStorm'],
+  rubymine: ['RubyMine'],
+  clion: ['CLion'],
+  goland: ['GoLand'],
+  rider: ['Rider'],
+  datagrip: ['DataGrip'],
+  appcode: ['AppCode'],
+  dataspell: ['DataSpell'],
+  aqua: ['Aqua'],
+  gateway: ['Gateway'],
+  fleet: ['Fleet'],
+  androidstudio: ['AndroidStudio'],
+}
+
+// Build plugin directory paths
+// https://www.jetbrains.com/help/pycharm/directories-used-by-the-ide-to-store-settings-caches-plugins-and-logs.html#plugins-directory
+function buildCommonPluginDirectoryPaths(ideName: string): string[] {
+  const homeDir = homedir()
+  const directories: string[] = []
+  const idePatterns = ideNameToDirMap[ideName.toLowerCase()]
+  if (!idePatterns) {
+    return directories
+  }
+
+  const appData = process.env.APPDATA || join(homeDir, 'AppData', 'Roaming')
+  const localAppData =
+    process.env.LOCALAPPDATA || join(homeDir, 'AppData', 'Local')
+
+  switch (platform()) {
+    case 'darwin':
+      directories.push(
+        join(homeDir, 'Library', 'Application Support', 'JetBrains'),
+        join(homeDir, 'Library', 'Application Support'),
+      )
+      if (ideName.toLowerCase() === 'androidstudio') {
+        directories.push(
+          join(homeDir, 'Library', 'Application Support', 'Google'),
+        )
+      }
+      break
+
+    case 'win32':
+      directories.push(
+        join(appData, 'JetBrains'),
+        join(localAppData, 'JetBrains'),
+        join(appData),
+      )
+      if (ideName.toLowerCase() === 'androidstudio') {
+        directories.push(join(localAppData, 'Google'))
+      }
+      break
+
+    case 'linux':
+      directories.push(
+        join(homeDir, '.config', 'JetBrains'),
+        join(homeDir, '.local', 'share', 'JetBrains'),
+      )
+      for (const pattern of idePatterns) {
+        directories.push(join(homeDir, '.' + pattern))
+      }
+      if (ideName.toLowerCase() === 'androidstudio') {
+        directories.push(join(homeDir, '.config', 'Google'))
+      }
+      break
+    default:
+      break
+  }
+
+  return directories
+}
+
+// Find all actual plugin directories that exist
+async function detectPluginDirectories(ideName: string): Promise<string[]> {
+  const foundDirectories: string[] = []
+  const fs = getFsImplementation()
+
+  const pluginDirPaths = buildCommonPluginDirectoryPaths(ideName)
+  const idePatterns = ideNameToDirMap[ideName.toLowerCase()]
+  if (!idePatterns) {
+    return foundDirectories
+  }
+
+  // Precompile once — idePatterns is invariant across baseDirs
+  const regexes = idePatterns.map(p => new RegExp('^' + p))
+
+  for (const baseDir of pluginDirPaths) {
+    try {
+      const entries = await fs.readdir(baseDir)
+      for (const regex of regexes) {
+        for (const entry of entries) {
+          if (!regex.test(entry.name)) continue
+          // Accept symlinks too — dirent.isDirectory() is false for symlinks,
+          // but GNU stow users symlink their JetBrains config dirs. Downstream
+          // fs.stat() calls will filter out symlinks that don't point to dirs.
+          if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+          const dir = join(baseDir, entry.name)
+          // Linux is the only OS to not have a plugins directory
+          if (platform() === 'linux') {
+            foundDirectories.push(dir)
+            continue
+          }
+          const pluginDir = join(dir, 'plugins')
+          try {
+            await fs.stat(pluginDir)
+            foundDirectories.push(pluginDir)
+          } catch {
+            // Plugin directory doesn't exist, skip
+          }
+        }
+      }
+    } catch {
+      // Ignore errors from stale IDE directories (ENOENT, EACCES, etc.)
+      continue
+    }
+  }
+
+  return foundDirectories.filter(
+    (dir, index) => foundDirectories.indexOf(dir) === index,
+  )
+}
+
+export async function isJetBrainsPluginInstalled(
+  ideType: IdeType,
+): Promise<boolean> {
+  const pluginDirs = await detectPluginDirectories(ideType)
+  for (const dir of pluginDirs) {
+    const pluginPath = join(dir, PLUGIN_PREFIX)
+    try {
+      await getFsImplementation().stat(pluginPath)
+      return true
+    } catch {
+      // Plugin not found in this directory, continue
+    }
+  }
+  return false
+}
+
+const pluginInstalledCache = new Map<IdeType, boolean>()
+const pluginInstalledPromiseCache = new Map<IdeType, Promise<boolean>>()
+
+async function isJetBrainsPluginInstalledMemoized(
+  ideType: IdeType,
+  forceRefresh = false,
+): Promise<boolean> {
+  if (!forceRefresh) {
+    const existing = pluginInstalledPromiseCache.get(ideType)
+    if (existing) {
+      return existing
+    }
+  }
+  const promise = isJetBrainsPluginInstalled(ideType).then(result => {
+    pluginInstalledCache.set(ideType, result)
+    return result
+  })
+  pluginInstalledPromiseCache.set(ideType, promise)
+  return promise
+}
+
+export async function isJetBrainsPluginInstalledCached(
+  ideType: IdeType,
+  forceRefresh = false,
+): Promise<boolean> {
+  if (forceRefresh) {
+    pluginInstalledCache.delete(ideType)
+    pluginInstalledPromiseCache.delete(ideType)
+  }
+  return isJetBrainsPluginInstalledMemoized(ideType, forceRefresh)
+}
+
+/**
+ * Returns the cached result of isJetBrainsPluginInstalled synchronously.
+ * Returns false if the result hasn't been resolved yet.
+ * Use this only in sync contexts (e.g., status notice isActive checks).
+ */
+export function isJetBrainsPluginInstalledCachedSync(
+  ideType: IdeType,
+): boolean {
+  return pluginInstalledCache.get(ideType) ?? false
+}