@xortex/xcode 3.0.0

package/utils/pasteStore.ts

@@ -0,0 +1,104 @@
+import { createHash } from 'crypto'
+import { mkdir, readdir, readFile, stat, unlink, writeFile } from 'fs/promises'
+import { join } from 'path'
+import { logForDebugging } from './debug.js'
+import { getClaudeConfigHomeDir } from './envUtils.js'
+import { isENOENT } from './errors.js'
+
+const PASTE_STORE_DIR = 'paste-cache'
+
+/**
+ * Get the paste store directory (persistent across sessions).
+ */
+function getPasteStoreDir(): string {
+  return join(getClaudeConfigHomeDir(), PASTE_STORE_DIR)
+}
+
+/**
+ * Generate a hash for paste content to use as filename.
+ * Exported so callers can get the hash synchronously before async storage.
+ */
+export function hashPastedText(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 16)
+}
+
+/**
+ * Get the file path for a paste by its content hash.
+ */
+function getPastePath(hash: string): string {
+  return join(getPasteStoreDir(), `${hash}.txt`)
+}
+
+/**
+ * Store pasted text content to disk.
+ * The hash should be pre-computed with hashPastedText() so the caller
+ * can use it immediately without waiting for the async disk write.
+ */
+export async function storePastedText(
+  hash: string,
+  content: string,
+): Promise<void> {
+  try {
+    const dir = getPasteStoreDir()
+    await mkdir(dir, { recursive: true })
+
+    const pastePath = getPastePath(hash)
+
+    // Content-addressable: same hash = same content, so overwriting is safe
+    await writeFile(pastePath, content, { encoding: 'utf8', mode: 0o600 })
+    logForDebugging(`Stored paste ${hash} to ${pastePath}`)
+  } catch (error) {
+    logForDebugging(`Failed to store paste: ${error}`)
+  }
+}
+
+/**
+ * Retrieve pasted text content by its hash.
+ * Returns null if not found or on error.
+ */
+export async function retrievePastedText(hash: string): Promise<string | null> {
+  try {
+    const pastePath = getPastePath(hash)
+    return await readFile(pastePath, { encoding: 'utf8' })
+  } catch (error) {
+    // ENOENT is expected when paste doesn't exist
+    if (!isENOENT(error)) {
+      logForDebugging(`Failed to retrieve paste ${hash}: ${error}`)
+    }
+    return null
+  }
+}
+
+/**
+ * Clean up old paste files that are no longer referenced.
+ * This is a simple time-based cleanup - removes files older than cutoffDate.
+ */
+export async function cleanupOldPastes(cutoffDate: Date): Promise<void> {
+  const pasteDir = getPasteStoreDir()
+
+  let files
+  try {
+    files = await readdir(pasteDir)
+  } catch {
+    // Directory doesn't exist or can't be read - nothing to clean up
+    return
+  }
+
+  const cutoffTime = cutoffDate.getTime()
+  for (const file of files) {
+    if (!file.endsWith('.txt')) {
+      continue
+    }
+
+    const filePath = join(pasteDir, file)
+    try {
+      const stats = await stat(filePath)
+      if (stats.mtimeMs < cutoffTime) {
+        await unlink(filePath)
+        logForDebugging(`Cleaned up old paste: ${filePath}`)
+      }
+    } catch {
+      // Ignore errors for individual files
+    }
+  }
+}

package/utils/path.ts

@@ -0,0 +1,155 @@
+import { homedir } from 'os'
+import { dirname, isAbsolute, join, normalize, relative, resolve } from 'path'
+import { getCwd } from './cwd.js'
+import { getFsImplementation } from './fsOperations.js'
+import { getPlatform } from './platform.js'
+import { posixPathToWindowsPath } from './windowsPaths.js'
+
+/**
+ * Expands a path that may contain tilde notation (~) to an absolute path.
+ *
+ * On Windows, POSIX-style paths (e.g., `/c/Users/...`) are automatically converted
+ * to Windows format (e.g., `C:\Users\...`). The function always returns paths in
+ * the native format for the current platform.
+ *
+ * @param path - The path to expand, may contain:
+ *   - `~` - expands to user's home directory
+ *   - `~/path` - expands to path within user's home directory
+ *   - absolute paths - returned normalized
+ *   - relative paths - resolved relative to baseDir
+ *   - POSIX paths on Windows - converted to Windows format
+ * @param baseDir - The base directory for resolving relative paths (defaults to current working directory)
+ * @returns The expanded absolute path in the native format for the current platform
+ *
+ * @throws {Error} If path is invalid
+ *
+ * @example
+ * expandPath('~') // '/home/user'
+ * expandPath('~/Documents') // '/home/user/Documents'
+ * expandPath('./src', '/project') // '/project/src'
+ * expandPath('/absolute/path') // '/absolute/path'
+ */
+export function expandPath(path: string, baseDir?: string): string {
+  // Set default baseDir to getCwd() if not provided
+  const actualBaseDir = baseDir ?? getCwd() ?? getFsImplementation().cwd()
+
+  // Input validation
+  if (typeof path !== 'string') {
+    throw new TypeError(`Path must be a string, received ${typeof path}`)
+  }
+
+  if (typeof actualBaseDir !== 'string') {
+    throw new TypeError(
+      `Base directory must be a string, received ${typeof actualBaseDir}`,
+    )
+  }
+
+  // Security: Check for null bytes
+  if (path.includes('\0') || actualBaseDir.includes('\0')) {
+    throw new Error('Path contains null bytes')
+  }
+
+  // Handle empty or whitespace-only paths
+  const trimmedPath = path.trim()
+  if (!trimmedPath) {
+    return normalize(actualBaseDir).normalize('NFC')
+  }
+
+  // Handle home directory notation
+  if (trimmedPath === '~') {
+    return homedir().normalize('NFC')
+  }
+
+  if (trimmedPath.startsWith('~/')) {
+    return join(homedir(), trimmedPath.slice(2)).normalize('NFC')
+  }
+
+  // On Windows, convert POSIX-style paths (e.g., /c/Users/...) to Windows format
+  let processedPath = trimmedPath
+  if (getPlatform() === 'windows' && trimmedPath.match(/^\/[a-z]\//i)) {
+    try {
+      processedPath = posixPathToWindowsPath(trimmedPath)
+    } catch {
+      // If conversion fails, use original path
+      processedPath = trimmedPath
+    }
+  }
+
+  // Handle absolute paths
+  if (isAbsolute(processedPath)) {
+    return normalize(processedPath).normalize('NFC')
+  }
+
+  // Handle relative paths
+  return resolve(actualBaseDir, processedPath).normalize('NFC')
+}
+
+/**
+ * Converts an absolute path to a relative path from cwd, to save tokens in
+ * tool output. If the path is outside cwd (relative path would start with ..),
+ * returns the absolute path unchanged so it stays unambiguous.
+ *
+ * @param absolutePath - The absolute path to relativize
+ * @returns Relative path if under cwd, otherwise the original absolute path
+ */
+export function toRelativePath(absolutePath: string): string {
+  const relativePath = relative(getCwd(), absolutePath)
+  // If the relative path would go outside cwd (starts with ..), keep absolute
+  return relativePath.startsWith('..') ? absolutePath : relativePath
+}
+
+/**
+ * Gets the directory path for a given file or directory path.
+ * If the path is a directory, returns the path itself.
+ * If the path is a file or doesn't exist, returns the parent directory.
+ *
+ * @param path - The file or directory path
+ * @returns The directory path
+ */
+export function getDirectoryForPath(path: string): string {
+  const absolutePath = expandPath(path)
+  // SECURITY: Skip filesystem operations for UNC paths to prevent NTLM credential leaks.
+  if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
+    return dirname(absolutePath)
+  }
+  try {
+    const stats = getFsImplementation().statSync(absolutePath)
+    if (stats.isDirectory()) {
+      return absolutePath
+    }
+  } catch {
+    // Path doesn't exist or can't be accessed
+  }
+  // If it's not a directory or doesn't exist, return the parent directory
+  return dirname(absolutePath)
+}
+
+/**
+ * Checks if a path contains directory traversal patterns that navigate to parent directories.
+ *
+ * @param path - The path to check for traversal patterns
+ * @returns true if the path contains traversal (e.g., '../', '..\', or ends with '..')
+ */
+export function containsPathTraversal(path: string): boolean {
+  return /(?:^|[\\/])\.\.(?:[\\/]|$)/.test(path)
+}
+
+// Re-export from the shared zero-dep source.
+export { sanitizePath } from './sessionStoragePortable.js'
+
+/**
+ * Normalizes a path for use as a JSON config key.
+ * On Windows, paths can have inconsistent separators (C:\path vs C:/path)
+ * depending on whether they come from git, Node.js APIs, or user input.
+ * This normalizes to forward slashes for consistent JSON serialization.
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path with consistent forward slashes
+ */
+export function normalizePathForConfigKey(path: string): string {
+  // First use Node's normalize to resolve . and .. segments
+  const normalized = normalize(path)
+  // Then convert all backslashes to forward slashes for consistent JSON keys
+  // This is safe because forward slashes work in Windows paths for most operations
+  return normalized.replace(/\\/g, '/')
+}

package/utils/pdf.ts

@@ -0,0 +1,300 @@
+import { randomUUID } from 'crypto'
+import { mkdir, readdir, readFile } from 'fs/promises'
+import { join } from 'path'
+import {
+  PDF_MAX_EXTRACT_SIZE,
+  PDF_TARGET_RAW_SIZE,
+} from '../constants/apiLimits.js'
+import { errorMessage } from './errors.js'
+import { execFileNoThrow } from './execFileNoThrow.js'
+import { formatFileSize } from './format.js'
+import { getFsImplementation } from './fsOperations.js'
+import { getToolResultsDir } from './toolResultStorage.js'
+
+export type PDFError = {
+  reason:
+    | 'empty'
+    | 'too_large'
+    | 'password_protected'
+    | 'corrupted'
+    | 'unknown'
+    | 'unavailable'
+  message: string
+}
+
+export type PDFResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: PDFError }
+
+/**
+ * Read a PDF file and return it as base64-encoded data.
+ * @param filePath Path to the PDF file
+ * @returns Result containing PDF data or a structured error
+ */
+export async function readPDF(filePath: string): Promise<
+  PDFResult<{
+    type: 'pdf'
+    file: {
+      filePath: string
+      base64: string
+      originalSize: number
+    }
+  }>
+> {
+  try {
+    const fs = getFsImplementation()
+    const stats = await fs.stat(filePath)
+    const originalSize = stats.size
+
+    // Check if file is empty
+    if (originalSize === 0) {
+      return {
+        success: false,
+        error: { reason: 'empty', message: `PDF file is empty: ${filePath}` },
+      }
+    }
+
+    // Check if PDF exceeds maximum size
+    // The API has a 32MB total request limit. After base64 encoding (~33% larger),
+    // a PDF must be under ~20MB raw to leave room for conversation context.
+    if (originalSize > PDF_TARGET_RAW_SIZE) {
+      return {
+        success: false,
+        error: {
+          reason: 'too_large',
+          message: `PDF file exceeds maximum allowed size of ${formatFileSize(PDF_TARGET_RAW_SIZE)}.`,
+        },
+      }
+    }
+
+    const fileBuffer = await readFile(filePath)
+
+    // Validate PDF magic bytes — reject files that aren't actually PDFs
+    // (e.g., HTML files renamed to .pdf) before they enter conversation context.
+    // Once an invalid PDF document block is in the message history, every subsequent
+    // API call fails with 400 "The PDF specified was not valid" and the session
+    // becomes unrecoverable without /clear.
+    const header = fileBuffer.subarray(0, 5).toString('ascii')
+    if (!header.startsWith('%PDF-')) {
+      return {
+        success: false,
+        error: {
+          reason: 'corrupted',
+          message: `File is not a valid PDF (missing %PDF- header): ${filePath}`,
+        },
+      }
+    }
+
+    const base64 = fileBuffer.toString('base64')
+
+    // Note: We cannot check page count here without parsing the PDF
+    // The API will enforce the 100-page limit and return an error if exceeded
+
+    return {
+      success: true,
+      data: {
+        type: 'pdf',
+        file: {
+          filePath,
+          base64,
+          originalSize,
+        },
+      },
+    }
+  } catch (e: unknown) {
+    return {
+      success: false,
+      error: {
+        reason: 'unknown',
+        message: errorMessage(e),
+      },
+    }
+  }
+}
+
+/**
+ * Get the number of pages in a PDF file using `pdfinfo` (from poppler-utils).
+ * Returns `null` if pdfinfo is not available or if the page count cannot be determined.
+ */
+export async function getPDFPageCount(
+  filePath: string,
+): Promise<number | null> {
+  const { code, stdout } = await execFileNoThrow('pdfinfo', [filePath], {
+    timeout: 10_000,
+    useCwd: false,
+  })
+  if (code !== 0) {
+    return null
+  }
+  const match = /^Pages:\s+(\d+)/m.exec(stdout)
+  if (!match) {
+    return null
+  }
+  const count = parseInt(match[1]!, 10)
+  return isNaN(count) ? null : count
+}
+
+export type PDFExtractPagesResult = {
+  type: 'parts'
+  file: {
+    filePath: string
+    originalSize: number
+    count: number
+    outputDir: string
+  }
+}
+
+let pdftoppmAvailable: boolean | undefined
+
+/**
+ * Reset the pdftoppm availability cache. Used by tests only.
+ */
+export function resetPdftoppmCache(): void {
+  pdftoppmAvailable = undefined
+}
+
+/**
+ * Check whether the `pdftoppm` binary (from poppler-utils) is available.
+ * The result is cached for the lifetime of the process.
+ */
+export async function isPdftoppmAvailable(): Promise<boolean> {
+  if (pdftoppmAvailable !== undefined) return pdftoppmAvailable
+  const { code, stderr } = await execFileNoThrow('pdftoppm', ['-v'], {
+    timeout: 5000,
+    useCwd: false,
+  })
+  // pdftoppm prints version info to stderr and exits 0 (or sometimes 99 on older versions)
+  pdftoppmAvailable = code === 0 || stderr.length > 0
+  return pdftoppmAvailable
+}
+
+/**
+ * Extract PDF pages as JPEG images using pdftoppm.
+ * Produces page-01.jpg, page-02.jpg, etc. in an output directory.
+ * This enables reading large PDFs and works with all API providers.
+ *
+ * @param filePath Path to the PDF file
+ * @param options Optional page range (1-indexed, inclusive)
+ */
+export async function extractPDFPages(
+  filePath: string,
+  options?: { firstPage?: number; lastPage?: number },
+): Promise<PDFResult<PDFExtractPagesResult>> {
+  try {
+    const fs = getFsImplementation()
+    const stats = await fs.stat(filePath)
+    const originalSize = stats.size
+
+    if (originalSize === 0) {
+      return {
+        success: false,
+        error: { reason: 'empty', message: `PDF file is empty: ${filePath}` },
+      }
+    }
+
+    if (originalSize > PDF_MAX_EXTRACT_SIZE) {
+      return {
+        success: false,
+        error: {
+          reason: 'too_large',
+          message: `PDF file exceeds maximum allowed size for text extraction (${formatFileSize(PDF_MAX_EXTRACT_SIZE)}).`,
+        },
+      }
+    }
+
+    const available = await isPdftoppmAvailable()
+    if (!available) {
+      return {
+        success: false,
+        error: {
+          reason: 'unavailable',
+          message:
+            'pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.',
+        },
+      }
+    }
+
+    const uuid = randomUUID()
+    const outputDir = join(getToolResultsDir(), `pdf-${uuid}`)
+    await mkdir(outputDir, { recursive: true })
+
+    // pdftoppm produces files like <prefix>-01.jpg, <prefix>-02.jpg, etc.
+    const prefix = join(outputDir, 'page')
+    const args = ['-jpeg', '-r', '100']
+    if (options?.firstPage) {
+      args.push('-f', String(options.firstPage))
+    }
+    if (options?.lastPage && options.lastPage !== Infinity) {
+      args.push('-l', String(options.lastPage))
+    }
+    args.push(filePath, prefix)
+    const { code, stderr } = await execFileNoThrow('pdftoppm', args, {
+      timeout: 120_000,
+      useCwd: false,
+    })
+
+    if (code !== 0) {
+      if (/password/i.test(stderr)) {
+        return {
+          success: false,
+          error: {
+            reason: 'password_protected',
+            message:
+              'PDF is password-protected. Please provide an unprotected version.',
+          },
+        }
+      }
+      if (/damaged|corrupt|invalid/i.test(stderr)) {
+        return {
+          success: false,
+          error: {
+            reason: 'corrupted',
+            message: 'PDF file is corrupted or invalid.',
+          },
+        }
+      }
+      return {
+        success: false,
+        error: { reason: 'unknown', message: `pdftoppm failed: ${stderr}` },
+      }
+    }
+
+    // Read generated image files and sort naturally
+    const entries = await readdir(outputDir)
+    const imageFiles = entries.filter(f => f.endsWith('.jpg')).sort()
+    const pageCount = imageFiles.length
+
+    if (pageCount === 0) {
+      return {
+        success: false,
+        error: {
+          reason: 'corrupted',
+          message: 'pdftoppm produced no output pages. The PDF may be invalid.',
+        },
+      }
+    }
+
+    const count = imageFiles.length
+
+    return {
+      success: true,
+      data: {
+        type: 'parts',
+        file: {
+          filePath,
+          originalSize,
+          outputDir,
+          count,
+        },
+      },
+    }
+  } catch (e: unknown) {
+    return {
+      success: false,
+      error: {
+        reason: 'unknown',
+        message: errorMessage(e),
+      },
+    }
+  }
+}

package/utils/pdfUtils.ts

@@ -0,0 +1,70 @@
+import { getMainLoopModel } from './model/model.js'
+
+// Document extensions that are handled specially
+export const DOCUMENT_EXTENSIONS = new Set(['pdf'])
+
+/**
+ * Parse a page range string into firstPage/lastPage numbers.
+ * Supported formats:
+ * - "5" → { firstPage: 5, lastPage: 5 }
+ * - "1-10" → { firstPage: 1, lastPage: 10 }
+ * - "3-" → { firstPage: 3, lastPage: Infinity }
+ *
+ * Returns null on invalid input (non-numeric, zero, inverted range).
+ * Pages are 1-indexed.
+ */
+export function parsePDFPageRange(
+  pages: string,
+): { firstPage: number; lastPage: number } | null {
+  const trimmed = pages.trim()
+  if (!trimmed) {
+    return null
+  }
+
+  // "N-" open-ended range
+  if (trimmed.endsWith('-')) {
+    const first = parseInt(trimmed.slice(0, -1), 10)
+    if (isNaN(first) || first < 1) {
+      return null
+    }
+    return { firstPage: first, lastPage: Infinity }
+  }
+
+  const dashIndex = trimmed.indexOf('-')
+  if (dashIndex === -1) {
+    // Single page: "5"
+    const page = parseInt(trimmed, 10)
+    if (isNaN(page) || page < 1) {
+      return null
+    }
+    return { firstPage: page, lastPage: page }
+  }
+
+  // Range: "1-10"
+  const first = parseInt(trimmed.slice(0, dashIndex), 10)
+  const last = parseInt(trimmed.slice(dashIndex + 1), 10)
+  if (isNaN(first) || isNaN(last) || first < 1 || last < 1 || last < first) {
+    return null
+  }
+  return { firstPage: first, lastPage: last }
+}
+
+/**
+ * Check if PDF reading is supported with the current model.
+ * PDF document blocks work on all providers (1P, Vertex, Bedrock, Foundry).
+ * Haiku 3 is the only remaining model that predates PDF support; users on
+ * it fall back to the page-extraction path (poppler-utils). Substring match
+ * covers all provider ID formats (Bedrock prefixes, Vertex @-dates).
+ */
+export function isPDFSupported(): boolean {
+  return !getMainLoopModel().toLowerCase().includes('claude-3-haiku')
+}
+
+/**
+ * Check if a file extension is a PDF document.
+ * @param ext File extension (with or without leading dot)
+ */
+export function isPDFExtension(ext: string): boolean {
+  const normalized = ext.startsWith('.') ? ext.slice(1) : ext
+  return DOCUMENT_EXTENSIONS.has(normalized.toLowerCase())
+}

package/utils/peerAddress.ts

@@ -0,0 +1,21 @@
+/**
+ * Peer address parsing — kept separate from peerRegistry.ts so that
+ * SendMessageTool can import parseAddress without transitively loading
+ * the bridge (axios) and UDS (fs, net) modules at tool-enumeration time.
+ */
+
+/** Parse a URI-style address into scheme + target. */
+export function parseAddress(to: string): {
+  scheme: 'uds' | 'bridge' | 'other'
+  target: string
+} {
+  if (to.startsWith('uds:')) return { scheme: 'uds', target: to.slice(4) }
+  if (to.startsWith('bridge:')) return { scheme: 'bridge', target: to.slice(7) }
+  // Legacy: old-code UDS senders emit bare socket paths in from=; route them
+  // through the UDS branch so replies aren't silently dropped into teammate
+  // routing. (No bare-session-ID fallback — bridge messaging is new enough
+  // that no old senders exist, and the prefix would hijack teammate names
+  // like session_manager.)
+  if (to.startsWith('/')) return { scheme: 'uds', target: to }
+  return { scheme: 'other', target: to }
+}