@suco/su-auggie-mcp 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @suco/su-auggie-mcp
+
+An MCP (Model Context Protocol) server that exposes [Augment Code](https://augmentcode.com) context engine capabilities.
+
+> ⚠️ **Experimental** — This package is a test implementation using the Auggie SDK. Use at your own risk.
+
+## Installation
+
+```bash
+npm install -g @suco/su-auggie-mcp
+```
+
+Or use with npx:
+
+```bash
+npx @suco/su-auggie-mcp
+```
+
+## Usage
+
+### As an MCP Server
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "su-auggie-mcp": {
+      "command": "npx",
+      "args": ["@suco/su-auggie-mcp"]
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `AUGMENT_API_KEY` — Your Augment Code API key (required)
+
+## Requirements
+
+- Node.js >= 20
+
+## License
+
+UNLICENSED
+

package/dist/adaptive-batcher.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Adaptive batching with self-tuning concurrency
+ * Batches by content size, adjusts parallelism based on throughput
+ */
+/** File entry for batching */
+export interface FileEntry {
+    path: string;
+    contents: string;
+}
+/** Batch with metadata */
+export interface Batch {
+    files: FileEntry[];
+    totalBytes: number;
+}
+/** Batching configuration */
+export interface AdaptiveBatcherConfig {
+    /** Target bytes per batch (default: 2MB) */
+    targetBatchBytes?: number;
+    /** Max files per batch (default: 1000, SDK limit) */
+    maxFilesPerBatch?: number;
+    /** Initial concurrency (default: 1) */
+    initialConcurrency?: number;
+    /** Minimum concurrency floor (default: 1) */
+    minConcurrency?: number;
+    /** Time threshold to increase concurrency in ms (default: 1500) */
+    fastThresholdMs?: number;
+    /** Time threshold to decrease concurrency in ms (default: 3000) */
+    slowThresholdMs?: number;
+}
+/** Metrics for monitoring */
+export interface BatcherMetrics {
+    totalBatches: number;
+    totalFiles: number;
+    totalBytes: number;
+    currentConcurrency: number;
+    avgBatchTimeMs: number;
+    peakConcurrency: number;
+    concurrencyBounds: {
+        min: number;
+        max: number;
+    };
+    batchLimits: {
+        maxBytes: number;
+        maxFiles: number;
+    };
+}
+/** Adaptive batcher with self-tuning concurrency */
+export declare class AdaptiveBatcher {
+    private config;
+    private concurrency;
+    private peakConcurrency;
+    private batchTimes;
+    private totalBatches;
+    private totalFiles;
+    private totalBytes;
+    constructor(config?: AdaptiveBatcherConfig);
+    /** Get current concurrency level */
+    getConcurrency(): number;
+    /** Get batch size limits for streaming batching */
+    getBatchLimits(): {
+        maxBytes: number;
+        maxFiles: number;
+    };
+    /** Get metrics for monitoring */
+    getMetrics(): BatcherMetrics;
+    /** Record batch completion and adjust concurrency */
+    recordBatchComplete(timeMs: number, fileCount: number, bytes: number, error?: boolean, rateLimited?: boolean): void;
+    /** Create batches from files based on target byte size and max file count */
+    createBatches(files: FileEntry[]): Generator<Batch>;
+}

package/dist/adaptive-batcher.js

@@ -0,0 +1,119 @@
+/**
+ * Adaptive batching with self-tuning concurrency
+ * Batches by content size, adjusts parallelism based on throughput
+ */
+import { INDEXING_CONFIG } from './config.js';
+import { createLogger } from './logger.js';
+const logger = createLogger('AdaptiveBatcher');
+/** Default configuration - uses INDEXING_CONFIG for tunables */
+const DEFAULT_CONFIG = {
+    targetBatchBytes: INDEXING_CONFIG.BATCH_MAX_BYTES, // Default: 8MB (configurable)
+    maxFilesPerBatch: INDEXING_CONFIG.BATCH_MAX_FILES, // Default: 1000 (configurable)
+    initialConcurrency: INDEXING_CONFIG.INITIAL_CONCURRENCY, // Default: 4 (configurable)
+    minConcurrency: 1,
+    fastThresholdMs: 1500, // <1.5s = increase concurrency
+    slowThresholdMs: 3000, // >3s = decrease concurrency
+};
+/** Adaptive batcher with self-tuning concurrency */
+export class AdaptiveBatcher {
+    config;
+    concurrency;
+    peakConcurrency;
+    batchTimes = [];
+    totalBatches = 0;
+    totalFiles = 0;
+    totalBytes = 0;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.concurrency = this.config.initialConcurrency;
+        this.peakConcurrency = this.concurrency;
+    }
+    /** Get current concurrency level */
+    getConcurrency() {
+        return this.concurrency;
+    }
+    /** Get batch size limits for streaming batching */
+    getBatchLimits() {
+        return {
+            maxBytes: this.config.targetBatchBytes,
+            maxFiles: this.config.maxFilesPerBatch,
+        };
+    }
+    /** Get metrics for monitoring */
+    getMetrics() {
+        const avgBatchTimeMs = this.batchTimes.length > 0
+            ? this.batchTimes.reduce((a, b) => a + b, 0) / this.batchTimes.length
+            : 0;
+        return {
+            totalBatches: this.totalBatches,
+            totalFiles: this.totalFiles,
+            totalBytes: this.totalBytes,
+            currentConcurrency: this.concurrency,
+            avgBatchTimeMs: Math.round(avgBatchTimeMs),
+            peakConcurrency: this.peakConcurrency,
+            concurrencyBounds: {
+                min: this.config.minConcurrency,
+                max: 20, // Hard-coded max in adjustConcurrency
+            },
+            batchLimits: {
+                maxBytes: this.config.targetBatchBytes,
+                maxFiles: this.config.maxFilesPerBatch,
+            },
+        };
+    }
+    /** Record batch completion and adjust concurrency */
+    recordBatchComplete(timeMs, fileCount, bytes, error, rateLimited) {
+        this.totalBatches++;
+        this.totalFiles += fileCount;
+        this.totalBytes += bytes;
+        this.batchTimes.push(timeMs);
+        // Keep last 20 batch times for averaging
+        if (this.batchTimes.length > 20) {
+            this.batchTimes.shift();
+        }
+        const oldConcurrency = this.concurrency;
+        if (rateLimited) {
+            // Rate limited - back off 50%
+            this.concurrency = Math.max(this.config.minConcurrency, Math.floor(this.concurrency * 0.5));
+            logger.warn(`Rate limited, reducing concurrency: ${oldConcurrency} -> ${this.concurrency}`);
+        }
+        else if (error) {
+            // Error - back off 30%
+            this.concurrency = Math.max(this.config.minConcurrency, Math.floor(this.concurrency * 0.7));
+            logger.debug(`Batch error, reducing concurrency: ${oldConcurrency} -> ${this.concurrency}`);
+        }
+        else if (timeMs < this.config.fastThresholdMs) {
+            // Fast - increase concurrency
+            this.concurrency++;
+            this.peakConcurrency = Math.max(this.peakConcurrency, this.concurrency);
+            logger.debug(`Fast batch (${timeMs}ms), increasing concurrency: ${oldConcurrency} -> ${this.concurrency}`);
+        }
+        else if (timeMs > this.config.slowThresholdMs) {
+            // Slow - decrease concurrency
+            this.concurrency = Math.max(this.config.minConcurrency, this.concurrency - 1);
+            logger.debug(`Slow batch (${timeMs}ms), reducing concurrency: ${oldConcurrency} -> ${this.concurrency}`);
+        }
+    }
+    /** Create batches from files based on target byte size and max file count */
+    *createBatches(files) {
+        let currentBatch = [];
+        let currentBytes = 0;
+        for (const file of files) {
+            const fileBytes = Buffer.byteLength(file.contents, 'utf-8');
+            // If adding this file exceeds byte target OR file count limit, yield current batch first
+            const exceedsByteLimit = currentBytes > 0 && currentBytes + fileBytes > this.config.targetBatchBytes;
+            const exceedsFileLimit = currentBatch.length >= this.config.maxFilesPerBatch;
+            if (exceedsByteLimit || exceedsFileLimit) {
+                yield { files: currentBatch, totalBytes: currentBytes };
+                currentBatch = [];
+                currentBytes = 0;
+            }
+            currentBatch.push(file);
+            currentBytes += fileBytes;
+        }
+        // Yield remaining files
+        if (currentBatch.length > 0) {
+            yield { files: currentBatch, totalBytes: currentBytes };
+        }
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Authentication utilities for Augment API
+ * Checks credentials from environment variables and session file
+ */
+/** Callback for auth state changes */
+type AuthChangeCallback = (hasAuth: boolean) => void;
+/** Check if credentials exist in environment variables */
+export declare function hasEnvCredentials(): boolean;
+/** Check if session file exists and contains valid credentials */
+export declare function hasSessionCredentials(): boolean;
+/** Check if any credentials are available (env or session file) */
+export declare function hasCredentials(): boolean;
+/** Get session file path (for watching) */
+export declare function getSessionFilePath(): string;
+/** Register a callback for auth state changes */
+export declare function onAuthChange(callback: AuthChangeCallback): void;
+/** Start watching session file for changes */
+export declare function startSessionWatcher(): void;
+/** Stop watching session file */
+export declare function stopSessionWatcher(): void;
+export {};

package/dist/auth.js

@@ -0,0 +1,111 @@
+/**
+ * Authentication utilities for Augment API
+ * Checks credentials from environment variables and session file
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { createLogger } from './logger.js';
+import { sendLogToClient } from './mcp-notifications.js';
+const logger = createLogger('Auth');
+/** Path to Augment session file */
+const SESSION_FILE_PATH = path.join(os.homedir(), '.augment', 'session.json');
+/** Session file watcher state */
+let sessionWatcher = null;
+let authChangeCallbacks = [];
+let lastKnownAuthState = null;
+/** Check if credentials exist in environment variables */
+export function hasEnvCredentials() {
+    return !!(process.env.AUGMENT_API_TOKEN || process.env.AUGMENT_API_KEY);
+}
+/** Check if session file exists and contains valid credentials */
+export function hasSessionCredentials() {
+    try {
+        if (!fs.existsSync(SESSION_FILE_PATH)) {
+            return false;
+        }
+        const content = fs.readFileSync(SESSION_FILE_PATH, 'utf-8');
+        const session = JSON.parse(content);
+        // Check for token in session (accessToken is the actual field name)
+        return !!(session.accessToken || session.token || session.access_token || session.api_token);
+    }
+    catch (err) {
+        logger.debug('Failed to read session file', err);
+        return false;
+    }
+}
+/** Check if any credentials are available (env or session file) */
+export function hasCredentials() {
+    return hasEnvCredentials() || hasSessionCredentials();
+}
+/** Get session file path (for watching) */
+export function getSessionFilePath() {
+    return SESSION_FILE_PATH;
+}
+/** Register a callback for auth state changes */
+export function onAuthChange(callback) {
+    authChangeCallbacks.push(callback);
+}
+/** Start watching session file for changes */
+export function startSessionWatcher() {
+    if (sessionWatcher) {
+        logger.debug('Session watcher already running');
+        return;
+    }
+    const sessionDir = path.dirname(SESSION_FILE_PATH);
+    // Ensure directory exists before watching
+    if (!fs.existsSync(sessionDir)) {
+        try {
+            fs.mkdirSync(sessionDir, { recursive: true });
+        }
+        catch (err) {
+            logger.warn('Failed to create .augment directory for watching', err);
+            return;
+        }
+    }
+    lastKnownAuthState = hasCredentials();
+    logger.info(`Starting session file watcher (current auth: ${lastKnownAuthState})`);
+    try {
+        // Watch the directory to catch file creation
+        sessionWatcher = fs.watch(sessionDir, (eventType, filename) => {
+            if (filename === 'session.json') {
+                handleSessionFileChange();
+            }
+        });
+        sessionWatcher.on('error', (err) => {
+            logger.warn('Session watcher error', err);
+        });
+    }
+    catch (err) {
+        logger.warn('Failed to start session watcher', err);
+    }
+}
+/** Handle session file change */
+function handleSessionFileChange() {
+    const currentAuthState = hasCredentials();
+    if (currentAuthState !== lastKnownAuthState) {
+        logger.info(`Auth state changed: ${lastKnownAuthState} -> ${currentAuthState}`);
+        lastKnownAuthState = currentAuthState;
+        if (currentAuthState) {
+            sendLogToClient('info', 'Augment credentials detected. Starting indexing...');
+        }
+        // Notify all callbacks
+        for (const callback of authChangeCallbacks) {
+            try {
+                callback(currentAuthState);
+            }
+            catch (err) {
+                logger.error('Auth change callback error', err);
+            }
+        }
+    }
+}
+/** Stop watching session file */
+export function stopSessionWatcher() {
+    if (sessionWatcher) {
+        sessionWatcher.close();
+        sessionWatcher = null;
+        authChangeCallbacks = [];
+        logger.debug('Session watcher stopped');
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Configuration constants for suco-auggie-mcp
+ */
+/** Indexing batch configuration - tune based on experimentation */
+export declare const INDEXING_CONFIG: {
+    /** Batch size for streaming discovery (yield batch when this many files found) */
+    readonly DISCOVERY_BATCH_SIZE: 100;
+    /** Number of parallel batch indexing operations */
+    readonly PARALLEL_BATCHES: 3;
+    /** Maximum file size in bytes (SDK limit is 1MB) */
+    readonly MAX_FILE_SIZE: number;
+    /** Maximum bytes per batch (SDK default: 2MB, optimal: 4MB) */
+    readonly BATCH_MAX_BYTES: number;
+    /** Maximum files per batch (SDK default: 1000) */
+    readonly BATCH_MAX_FILES: number;
+    /** Initial concurrency for batch uploads */
+    readonly INITIAL_CONCURRENCY: number;
+    /** Maximum retry attempts for failed batches (0 = no retries) - Tier 1 immediate retries */
+    readonly MAX_RETRIES: number;
+    /** Base delay for exponential backoff in ms */
+    readonly RETRY_BASE_DELAY_MS: number;
+    /** Maximum delay between retries in ms */
+    readonly RETRY_MAX_DELAY_MS: number;
+    /** Tier 2: Cooldown period in ms before retrying failed files (default: 5 minutes) */
+    readonly COOLDOWN_PERIOD_MS: number;
+    /** Tier 2: Maximum cooldown cycles before giving up (default: 3) */
+    readonly MAX_COOLDOWN_CYCLES: number;
+};
+/** File watcher configuration */
+export declare const WATCHER_CONFIG: {
+    /** Debounce delay in ms before processing file changes */
+    readonly DEBOUNCE_MS: number;
+    /** Delay before initial scan starts after watcher ready */
+    readonly INITIAL_SCAN_DELAY_MS: 100;
+};
+/** Persistence configuration */
+export declare const PERSISTENCE_CONFIG: {
+    /** Directory name for state files within workspace */
+    readonly STATE_DIR: ".suco-auggie";
+    /** Filename for index state */
+    readonly STATE_FILE: "index-state.json";
+    /** Filename for file metadata (mtimes, sizes) */
+    readonly METADATA_FILE: "file-metadata.json";
+    /** Filename for cooldown queue (failed files awaiting retry) */
+    readonly COOLDOWN_FILE: "cooldown-queue.json";
+};
+/** Get debug mode */
+export declare function isDebugMode(): boolean;
+/** Set debug mode (called from CLI when --debug is passed) */
+export declare function setDebugMode(enabled: boolean): void;
+/** Check if persistence is enabled */
+export declare function isPersistenceEnabled(): boolean;
+/** Set persistence mode (called from CLI when --no-persistent is passed) */
+export declare function setPersistenceEnabled(enabled: boolean): void;
+/** @deprecated Use isDebugMode() instead */
+export declare const DEBUG: boolean;

package/dist/config.js

@@ -0,0 +1,68 @@
+/**
+ * Configuration constants for suco-auggie-mcp
+ */
+/** Indexing batch configuration - tune based on experimentation */
+export const INDEXING_CONFIG = {
+    /** Batch size for streaming discovery (yield batch when this many files found) */
+    DISCOVERY_BATCH_SIZE: 100,
+    /** Number of parallel batch indexing operations */
+    PARALLEL_BATCHES: 3,
+    /** Maximum file size in bytes (SDK limit is 1MB) */
+    MAX_FILE_SIZE: 1024 * 1024, // 1MB
+    /** Maximum bytes per batch (SDK default: 2MB, optimal: 4MB) */
+    BATCH_MAX_BYTES: parseInt(process.env.SUCO_AUGGIE_BATCH_MAX_BYTES || String(4 * 1024 * 1024), 10),
+    /** Maximum files per batch (SDK default: 1000) */
+    BATCH_MAX_FILES: parseInt(process.env.SUCO_AUGGIE_BATCH_MAX_FILES || '1000', 10),
+    /** Initial concurrency for batch uploads */
+    INITIAL_CONCURRENCY: parseInt(process.env.SUCO_AUGGIE_INITIAL_CONCURRENCY || '4', 10),
+    /** Maximum retry attempts for failed batches (0 = no retries) - Tier 1 immediate retries */
+    MAX_RETRIES: parseInt(process.env.SUCO_AUGGIE_MAX_RETRIES || '3', 10),
+    /** Base delay for exponential backoff in ms */
+    RETRY_BASE_DELAY_MS: parseInt(process.env.SUCO_AUGGIE_RETRY_BASE_DELAY_MS || '1000', 10),
+    /** Maximum delay between retries in ms */
+    RETRY_MAX_DELAY_MS: parseInt(process.env.SUCO_AUGGIE_RETRY_MAX_DELAY_MS || '30000', 10),
+    /** Tier 2: Cooldown period in ms before retrying failed files (default: 5 minutes) */
+    COOLDOWN_PERIOD_MS: parseInt(process.env.SUCO_AUGGIE_COOLDOWN_PERIOD_MS || String(5 * 60 * 1000), 10),
+    /** Tier 2: Maximum cooldown cycles before giving up (default: 3) */
+    MAX_COOLDOWN_CYCLES: parseInt(process.env.SUCO_AUGGIE_MAX_COOLDOWN_CYCLES || '3', 10),
+};
+/** File watcher configuration */
+export const WATCHER_CONFIG = {
+    /** Debounce delay in ms before processing file changes */
+    DEBOUNCE_MS: parseInt(process.env.SUCO_AUGGIE_DEBOUNCE_MS || '500', 10),
+    /** Delay before initial scan starts after watcher ready */
+    INITIAL_SCAN_DELAY_MS: 100,
+};
+/** Persistence configuration */
+export const PERSISTENCE_CONFIG = {
+    /** Directory name for state files within workspace */
+    STATE_DIR: '.suco-auggie',
+    /** Filename for index state */
+    STATE_FILE: 'index-state.json',
+    /** Filename for file metadata (mtimes, sizes) */
+    METADATA_FILE: 'file-metadata.json',
+    /** Filename for cooldown queue (failed files awaiting retry) */
+    COOLDOWN_FILE: 'cooldown-queue.json',
+};
+/** Debug mode - can be set via env var or CLI flag */
+let debugMode = process.env.SUCO_AUGGIE_DEBUG === '1';
+/** Get debug mode */
+export function isDebugMode() {
+    return debugMode;
+}
+/** Set debug mode (called from CLI when --debug is passed) */
+export function setDebugMode(enabled) {
+    debugMode = enabled;
+}
+/** Persistence mode - enabled by default, can be disabled via CLI */
+let persistenceEnabled = true;
+/** Check if persistence is enabled */
+export function isPersistenceEnabled() {
+    return persistenceEnabled;
+}
+/** Set persistence mode (called from CLI when --no-persistent is passed) */
+export function setPersistenceEnabled(enabled) {
+    persistenceEnabled = enabled;
+}
+/** @deprecated Use isDebugMode() instead */
+export const DEBUG = process.env.SUCO_AUGGIE_DEBUG === '1';

package/dist/file-indexer.d.ts

@@ -0,0 +1,154 @@
+/**
+ * FileIndexer - Centralized file indexing with file-level error handling.
+ *
+ * Single entry point for ALL file indexing operations:
+ * - Initial discovery indexing
+ * - File watcher changes
+ * - Retry (tier 1 & tier 2)
+ *
+ * Errors are handled at FILE level, not BATCH level.
+ */
+import { DirectContext } from '@augmentcode/auggie-sdk';
+import { AdaptiveBatcher } from './adaptive-batcher.js';
+import type { FileMetadataMap } from './types.js';
+/** File-level error classification */
+export type FileErrorType = 'skip' | 'retryable' | 'permanent' | 'fatal';
+/** Result of attempting to index a file */
+export interface FileIndexResult {
+    path: string;
+    success: boolean;
+    error?: FileErrorType;
+    message?: string;
+}
+/** Statistics for FileIndexer */
+export interface FileIndexerStats {
+    /** Files successfully indexed */
+    indexed: number;
+    /** Files skipped (too large, binary, etc.) */
+    skipped: number;
+    /** Files in tier 1 retry queue */
+    pendingRetry: number;
+    /** Files in tier 2 cooldown queue */
+    pendingCooldown: number;
+    /** Files recovered via retry */
+    recovered: number;
+    /** Files permanently failed */
+    failed: number;
+    /** Current cooldown cycle */
+    cooldownCycle: number;
+    /** Next cooldown retry time */
+    cooldownNextRetryAt: string | null;
+}
+/** Callback for progress updates */
+export type ProgressCallback = (indexed: number, total: number, message: string) => void;
+/**
+ * Classify an error at the FILE level.
+ * Returns: skip | retryable | permanent | fatal
+ * @internal Exported for testing
+ */
+export declare function classifyFileError(err: unknown): FileErrorType;
+/**
+ * Check if a file is binary (non-text).
+ * Uses null byte detection in first 8KB.
+ * @internal Exported for testing
+ */
+export declare function isBinaryFile(buffer: Buffer): boolean;
+/**
+ * Calculate exponential backoff delay with jitter.
+ * @internal Exported for testing
+ */
+export declare function calculateBackoff(attempt: number): number;
+/**
+ * FileIndexer - centralized indexing with file-level error handling.
+ */
+export declare class FileIndexer {
+    private context;
+    private root;
+    private batcher;
+    private indexQueue;
+    private retryQueue;
+    private cooldownQueue;
+    private cooldownTimer;
+    private cooldownNextRetryAt;
+    private stats;
+    constructor(context: DirectContext, root: string);
+    /** Get current statistics */
+    getStats(): FileIndexerStats;
+    /** Get batcher metrics */
+    getBatcherMetrics(): import("./adaptive-batcher.js").BatcherMetrics;
+    /** Get batcher for external access */
+    getBatcher(): AdaptiveBatcher;
+    /**
+     * Pre-filter a file before reading contents.
+     * Returns null if file should be skipped, or file entry if valid.
+     */
+    private preFilterFile;
+    /**
+     * Index a batch of files with error isolation.
+     * On batch failure, isolates problematic files and retries good ones.
+     */
+    private indexBatchWithIsolation;
+    /**
+     * Route failed files to appropriate tier based on error type.
+     */
+    private routeFailedFiles;
+    /**
+     * Add a file to cooldown queue (tier 2).
+     */
+    private addToCooldown;
+    /**
+     * Process tier 1 retry queue.
+     */
+    processRetryQueue(): Promise<void>;
+    /**
+     * Schedule cooldown retry if not already scheduled.
+     */
+    private scheduleCooldownRetry;
+    /**
+     * Process cooldown queue (tier 2).
+     */
+    processCooldownQueue(): Promise<void>;
+    /**
+     * Main entry point: Index a list of file paths.
+     * Handles batching, pre-filtering, error isolation, and retry routing.
+     */
+    indexFiles(absolutePaths: string[], onProgress?: ProgressCallback): Promise<{
+        metadata: FileMetadataMap;
+        indexed: number;
+        skipped: number;
+    }>;
+    /**
+     * Index a single file (for watcher events).
+     */
+    indexSingleFile(absolutePath: string): Promise<boolean>;
+    /**
+     * Remove files from index.
+     */
+    removeFiles(relativePaths: string[]): Promise<void>;
+    /**
+     * Load cooldown queue from disk.
+     */
+    private loadCooldownQueue;
+    /**
+     * Save cooldown queue to disk.
+     */
+    private saveCooldownQueue;
+    /**
+     * Stop the indexer and clean up.
+     */
+    stop(): void;
+    /**
+     * Reset statistics (for reindex).
+     */
+    resetStats(): void;
+    /**
+     * Close the indexer (alias for stop).
+     */
+    close(): void;
+    /**
+     * Trigger retry if conditions are met (no pending work, has failed files).
+     * This is a "hit and run" call - triggers async retry and returns immediately.
+     * Used by tool calls to opportunistically retry failed files.
+     */
+    triggerRetryIfNeeded(): void;
+}