@augmentcode/auggie-sdk 0.1.11 → 0.1.13

package/README.md

@@ -312,9 +312,32 @@ const client = await Auggie.create({
   allowIndexing: true,
   apiKey: "your-api-key",  // Optional
   apiUrl: "https://your-tenant.api.augmentcode.com",  // Required when apiKey is provided
+  cliArgs: ["--verbose", "--timeout=30"],  // Optional: Additional CLI arguments
 });
 ```
 
+### Advanced CLI Arguments
+
+The `cliArgs` option allows you to pass additional command-line arguments directly to the Auggie CLI process. These arguments are appended after all SDK-generated flags.
+
+```typescript
+// Pass custom CLI flags
+const client = await Auggie.create({
+  model: "sonnet4.5",
+  cliArgs: ["--verbose", "--log-level=debug"]
+});
+
+// Arguments can use either format:
+// 1. Separate flag and value: ["--timeout", "30"]
+// 2. Combined with equals: ["--timeout=30"]
+const client2 = await Auggie.create({
+  model: "sonnet4.5",
+  cliArgs: ["--timeout=60", "--retries", "3"]
+});
+```
+
+Use this option for advanced configurations or experimental flags not exposed through standard SDK options. Refer to `auggie --help` for available CLI flags.
+
 ## Context Modes
 
 The SDK provides two context modes for codebase indexing and search.
@@ -334,11 +357,27 @@ import { DirectContext } from "@augmentcode/auggie-sdk";
 // 3. Or pass credentials directly in options
 const context = await DirectContext.create();
 
-// Add files to index
+// Add files to index (waits indefinitely by default)
 await context.addToIndex([
   { path: "src/main.ts", contents: "..." }
 ]);
 
+// Optionally set a timeout
+await context.addToIndex(files, {
+  timeout: 10 * 60 * 1000  // 10 minutes in milliseconds
+});
+
+// Track progress during indexing
+await context.addToIndex(files, {
+  onProgress: (progress) => {
+    console.log(`[${progress.stage}] Uploaded: ${progress.uploaded}/${progress.total}, Indexed: ${progress.indexed}/${progress.total}`);
+    if (progress.stage === 'uploading') {
+      console.log(`  Current file: ${progress.currentFile}`);
+      console.log(`  Bytes uploaded: ${progress.bytesUploaded}`);
+    }
+  }
+});
+
 // Search - returns results in a formatted string ready for LLM use or display
 const results = await context.search("authentication logic");
 console.log(results);
@@ -352,8 +391,47 @@ console.log(answer);
 
 // Export state to avoid re-indexing
 await context.exportToFile("/tmp/state.json");
+
+// For search-only use cases, export lightweight state
+await context.exportToFile("/tmp/search-state.json", { mode: "search-only" });
 ```
 
+#### Search-Only Export (Optimized for Storage)
+
+For applications that only need to search an existing index (without adding or removing files), you can export a lightweight search-only state that excludes the large blobs array:
+
+```typescript
+import { DirectContext } from "@augmentcode/auggie-sdk";
+
+// Create and index files normally
+const context = await DirectContext.create();
+await context.addToIndex(files);
+
+// Export search-only state (much smaller for large codebases)
+const searchState = context.export({ mode: "search-only" });
+// or
+await context.exportToFile("search-state.json", { mode: "search-only" });
+
+// Later, import the search-only state
+const searchContext = await DirectContext.import(searchState);
+// or
+const searchContext = await DirectContext.importFromFile("search-state.json");
+
+// Search operations work normally
+const results = await searchContext.search("authentication logic");
+
+// But indexing operations will throw errors
+// await searchContext.addToIndex(files); // ❌ Error: requires full state
+// await searchContext.removeFromIndex(paths); // ❌ Error: requires full state
+// searchContext.getIndexedPaths(); // ❌ Error: requires full state
+```
+
+**When to use search-only export:**
+- ✅ Search-only applications (e.g., documentation search, code Q&A)
+- ✅ Distributed systems where indexing happens centrally
+- ✅ Reducing index size for large codebases
+- ❌ Applications that need to add/remove files from the index
+
 ### FileSystem Context
 
 **⚠️ Requires Local Auggie Installation**
@@ -403,6 +481,7 @@ Creates and initializes a new Auggie instance. This method automatically connect
 - `apiKey?: string` - API key for authentication (optional, sets AUGMENT_API_TOKEN)
 - `apiUrl?: string` - API URL for authentication (optional, sets AUGMENT_API_URL)
 - `excludedTools?: ToolIdentifier[]` - List of tool identifiers to exclude/disable (optional)
+- `cliArgs?: string[]` - Additional command-line arguments to pass to the Auggie CLI process (optional, default: [])
 
 When `tools` (or `toolsMap`) is provided, an MCP server is automatically started and connected to the session.
 

package/dist/auggie/sdk-acp-client.d.ts

@@ -39,6 +39,33 @@ type AuggieOptions = {
      * ```
      */
     excludedTools?: ToolIdentifier[];
+    /**
+     * Additional command-line arguments to pass to the Auggie CLI process.
+     * These arguments are appended to the CLI command when spawning the process.
+     *
+     * Use this option to pass custom or advanced CLI flags that are not
+     * directly exposed through other AuggieOptions properties.
+     *
+     * Arguments can be provided as:
+     * - Flag-only arguments: `"--verbose"`
+     * - Flag with value (separate strings): `"--timeout", "30"`
+     * - Flag with value (single string): `"--timeout=30"`
+     *
+     * @example
+     * ```typescript
+     * // Pass a single flag
+     * cliArgs: ["--verbose"]
+     *
+     * // Pass multiple arguments with values
+     * cliArgs: ["--timeout", "30", "--retries", "3"]
+     *
+     * // Pass flags with equals-style values
+     * cliArgs: ["--timeout=30", "--retries=3"]
+     * ```
+     *
+     * @default []
+     */
+    cliArgs?: string[];
 };
 /**
  * ACP Client for connecting to Auggie as an ACP server
@@ -65,6 +92,7 @@ declare class Auggie {
     private readonly apiUrl;
     private readonly rules;
     private readonly excludedTools;
+    private readonly cliArgs;
     private constructor();
     /**
      * Create and initialize a new Auggie instance

package/dist/auggie/sdk-acp-client.js

@@ -24,6 +24,7 @@ class Auggie {
   apiUrl;
   rules;
   excludedTools;
+  cliArgs;
   constructor({
     auggiePath = "auggie",
     workspaceRoot,
@@ -32,7 +33,8 @@ class Auggie {
     apiKey,
     apiUrl = process.env.AUGMENT_API_URL || "https://api.augmentcode.com",
     rules,
-    excludedTools
+    excludedTools,
+    cliArgs = []
   } = {}) {
     this.auggiePath = auggiePath;
     this.workspaceRoot = workspaceRoot;
@@ -42,6 +44,7 @@ class Auggie {
     this.apiUrl = apiUrl;
     this.rules = rules;
     this.excludedTools = excludedTools;
+    this.cliArgs = cliArgs;
   }
   /**
    * Create and initialize a new Auggie instance
@@ -81,6 +84,9 @@ class Auggie {
         args.push("--remove-tool", tool);
       }
     }
+    if (this.cliArgs.length > 0) {
+      args.push(...this.cliArgs);
+    }
     const pathParts = this.auggiePath.trim().split(Auggie.PATH_SPLIT_REGEX);
     if (pathParts.length === 0 || !pathParts[0]) {
       throw new Error("Invalid auggiePath: cannot be empty");

package/dist/context/direct-context.d.ts

@@ -1,4 +1,4 @@
-import { DirectContextOptions, DirectContextState, File, IndexingResult } from './types.js';
+import { DirectContextOptions, DirectContextState, File, AddToIndexOptions, IndexingResult, IndexingProgress, ExportOptions } from './types.js';
 
 /**
  * Direct Context - API-based indexing with import/export state
@@ -43,6 +43,26 @@ import { DirectContextOptions, DirectContextState, File, IndexingResult } from '
  * await context.search("query");   // files are now indexed
  * ```
  *
+ * **Option 3: Set a timeout**
+ * ```typescript
+ * // By default, waits indefinitely. Set a timeout if needed:
+ * await context.addToIndex(files, { timeout: 10 * 60 * 1000 }); // 10 minutes
+ * // or
+ * await context.waitForIndexing(10 * 60 * 1000);
+ * ```
+ *
+ * **Option 4: Track progress during indexing**
+ * ```typescript
+ * await context.addToIndex(files, {
+ *   onProgress: (progress) => {
+ *     console.log(`[${progress.stage}] Uploaded: ${progress.uploaded}/${progress.total}, Indexed: ${progress.indexed}/${progress.total}`);
+ *     if (progress.stage === 'uploading') {
+ *       console.log(`  Bytes uploaded: ${progress.bytesUploaded}`);
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * Note: `search()` and `searchAndAsk()` do not wait for indexing automatically.
  *
  * ## State Persistence
@@ -99,6 +119,7 @@ declare class DirectContext {
     private checkpointId?;
     private pendingAdded;
     private pendingDeleted;
+    private isSearchOnly;
     private readonly mutex;
     private readonly pollingMutex;
     /**
@@ -140,12 +161,18 @@ declare class DirectContext {
      * Log a debug message if debug mode is enabled
      */
     private log;
+    /**
+     * Create a progress context for an operation
+     */
+    private createProgressContext;
     /**
      * Create a checkpoint if threshold is reached
      */
     private maybeCheckpoint;
     /**
      * Get the list of indexed file paths
+     *
+     * @throws Error if the context was imported from search-only state
      */
     getIndexedPaths(): string[];
     /**
@@ -158,11 +185,12 @@ declare class DirectContext {
      * @param files - Array of files to add to the index
      * @param options - Optional configuration
      * @param options.waitForIndexing - If true (default), waits for the newly added files to be indexed before returning
+     * @param options.timeout - Timeout in milliseconds for indexing operation (default: undefined = no timeout)
+     * @param options.onProgress - Optional callback to receive progress updates
      * @returns Result indicating which files were newly uploaded vs already uploaded
+     * @throws Error if the context was imported from search-only state
      */
-    addToIndex(files: File[], options?: {
-        waitForIndexing?: boolean;
-    }): Promise<IndexingResult>;
+    addToIndex(files: File[], options?: AddToIndexOptions): Promise<IndexingResult>;
     /**
      * Find blobs that are missing or not yet indexed on the backend (detailed result)
      * Batches requests in chunks of 1000
@@ -195,6 +223,8 @@ declare class DirectContext {
     private doAddToIndex;
     /**
      * Remove paths from the index
+     *
+     * @throws Error if the context was imported from search-only state
      */
     removeFromIndex(paths: string[]): Promise<void>;
     /**
@@ -214,6 +244,10 @@ declare class DirectContext {
      *
      * This method is serialized via pollingMutex to prevent unbounded concurrent
      * polling requests to the backend.
+     *
+     * @param blobNames - Array of blob names to wait for
+     * @param timeoutMs - Timeout in milliseconds (default: undefined = no timeout)
+     * @param ctx - Progress context for reporting
      */
     private waitForSpecificBlobs;
     /**
@@ -222,10 +256,12 @@ declare class DirectContext {
      * This method polls the backend until all files that have been added to the index
      * are confirmed to be indexed and searchable.
      *
+     * @param timeout - Timeout in milliseconds (default: undefined = no timeout)
+     * @param onProgress - Optional callback to receive progress updates
      * @returns Promise that resolves when all files are indexed
-     * @throws Error if indexing times out (default: 10 minutes)
+     * @throws Error if indexing times out (only when timeout is specified)
      */
-    waitForIndexing(): Promise<void>;
+    waitForIndexing(timeout?: number, onProgress?: (progress: IndexingProgress) => void): Promise<void>;
     /**
      * Search the codebase using natural language and return formatted results.
      *
@@ -272,16 +308,36 @@ declare class DirectContext {
     searchAndAsk(searchQuery: string, prompt?: string): Promise<string>;
     /**
      * Export the current state to a JSON object
+     *
+     * @param options Export options
+     * @param options.mode Export mode - 'full' (default) includes all blob information,
+     *                     'search-only' excludes blobs array for minimal storage
+     * @returns The exported state object
+     *
+     * @example
+     * ```typescript
+     * // Full export (default) - supports all operations
+     * const fullState = context.export();
+     * const fullState = context.export({ mode: 'full' });
+     *
+     * // Search-only export - much smaller, only supports search operations
+     * const searchState = context.export({ mode: 'search-only' });
+     * ```
      */
-    export(): DirectContextState;
+    export(options?: ExportOptions): DirectContextState;
     /**
      * Internal method to import state from a JSON object
      */
     private doImport;
     /**
      * Export state to a file (Node.js only)
+     *
+     * @param filePath Path to save the state file
+     * @param options Export options
+     * @param options.mode Export mode - 'full' (default) includes all blob information,
+     *                     'search-only' excludes blobs array for minimal storage
      */
-    exportToFile(filePath: string): Promise<void>;
+    exportToFile(filePath: string, options?: ExportOptions): Promise<void>;
 }
 
 export { DirectContext };

package/dist/context/direct-context.js

@@ -47,6 +47,8 @@ class DirectContext {
   checkpointId;
   pendingAdded = /* @__PURE__ */ new Set();
   pendingDeleted = /* @__PURE__ */ new Set();
+  // Track if this instance was imported from search-only state
+  isSearchOnly = false;
   // Mutex for serializing state-modifying operations (upload, checkpoint, etc.)
   mutex = new Mutex();
   // Mutex for serializing polling operations to prevent unbounded concurrent requests
@@ -118,6 +120,12 @@ class DirectContext {
       console.log(`[DirectContext] ${message}`);
     }
   }
+  /**
+   * Create a progress context for an operation
+   */
+  createProgressContext(onProgress, total, startedAt) {
+    return { onProgress, total, startedAt, uploaded: 0, indexed: 0 };
+  }
   /**
    * Create a checkpoint if threshold is reached
    */
@@ -147,8 +155,15 @@ class DirectContext {
   }
   /**
    * Get the list of indexed file paths
+   *
+   * @throws Error if the context was imported from search-only state
    */
   getIndexedPaths() {
+    if (this.isSearchOnly) {
+      throw new Error(
+        "Cannot call getIndexedPaths() on a context imported from search-only state. This operation requires full state with blob information. Import from a full state export instead."
+      );
+    }
     return Array.from(this.blobMap.keys());
   }
   /**
@@ -161,16 +176,30 @@ class DirectContext {
    * @param files - Array of files to add to the index
    * @param options - Optional configuration
    * @param options.waitForIndexing - If true (default), waits for the newly added files to be indexed before returning
+   * @param options.timeout - Timeout in milliseconds for indexing operation (default: undefined = no timeout)
+   * @param options.onProgress - Optional callback to receive progress updates
    * @returns Result indicating which files were newly uploaded vs already uploaded
+   * @throws Error if the context was imported from search-only state
    */
   async addToIndex(files, options) {
+    if (this.isSearchOnly) {
+      throw new Error(
+        "Cannot call addToIndex() on a context imported from search-only state. This operation requires full state with blob information for deduplication. Import from a full state export instead, or create a new context with DirectContext.create()."
+      );
+    }
     const waitForIndexing = options?.waitForIndexing ?? true;
+    const timeout = options?.timeout;
+    const ctx = this.createProgressContext(
+      options?.onProgress,
+      files.length,
+      /* @__PURE__ */ new Date()
+    );
     const result = await this.mutex.runExclusive(
-      () => this.doAddToIndex(files)
+      () => this.doAddToIndex(files, ctx)
     );
     if (waitForIndexing && result.newlyUploaded.length > 0) {
       const newlyUploadedBlobNames = result.newlyUploaded.map((path) => this.blobMap.get(path)).filter((blobName) => blobName !== void 0);
-      await this.waitForSpecificBlobs(newlyUploadedBlobNames);
+      await this.waitForSpecificBlobs(newlyUploadedBlobNames, timeout, ctx);
     }
     return result;
   }
@@ -199,7 +228,7 @@ class DirectContext {
    * Upload files in batches respecting backend limits
    * Returns a map of client-computed blob IDs to backend-returned blob IDs
    */
-  async batchUploadFiles(filesToUpload) {
+  async batchUploadFiles(filesToUpload, ctx) {
     const batches = [];
     let currentBatch = [];
     let currentBatchSize = 0;
@@ -222,6 +251,8 @@ class DirectContext {
       batches.push(currentBatch);
     }
     const blobIdMap = /* @__PURE__ */ new Map();
+    let filesProcessed = 0;
+    let bytesUploaded = 0;
     for (const batch of batches) {
       const result = await this.apiClient.batchUpload(batch);
       for (const [i, batchItem] of batch.entries()) {
@@ -231,6 +262,23 @@ class DirectContext {
           blobIdMap.set(clientBlobId, backendBlobId);
         }
       }
+      filesProcessed += batch.length;
+      ctx.uploaded = filesProcessed;
+      bytesUploaded += batch.reduce(
+        (sum, file) => sum + Buffer.byteLength(file.text, "utf-8"),
+        0
+      );
+      if (ctx.onProgress) {
+        ctx.onProgress({
+          stage: "uploading",
+          uploaded: ctx.uploaded,
+          indexed: ctx.indexed,
+          total: ctx.total,
+          currentFile: batch.at(-1)?.pathName,
+          bytesUploaded,
+          startedAt: ctx.startedAt
+        });
+      }
     }
     return blobIdMap;
   }
@@ -256,7 +304,10 @@ class DirectContext {
     const newBlobEntries = [];
     const alreadyUploaded = [];
     for (const file of files) {
-      const clientBlobId = this.blobCalculator.calculate(file.path, file.contents);
+      const clientBlobId = this.blobCalculator.calculate(
+        file.path,
+        file.contents
+      );
       if (clientBlobId) {
         const existingClientBlobId = this.clientBlobMap.get(file.path);
         if (existingClientBlobId && existingClientBlobId === clientBlobId) {
@@ -292,14 +343,16 @@ class DirectContext {
   /**
    * Internal implementation of addToIndex
    */
-  async doAddToIndex(files) {
+  async doAddToIndex(files, ctx) {
     this.log(`Adding ${files.length} files to index`);
     this.validateFileSizes(files);
     const { filesToUpload, newBlobEntries, alreadyUploaded } = this.prepareBlobsForUpload(files);
     if (newBlobEntries.length === 0) {
       return { newlyUploaded: [], alreadyUploaded };
     }
-    const blobNamesToCheck = newBlobEntries.map(([_, clientBlobId]) => clientBlobId);
+    const blobNamesToCheck = newBlobEntries.map(
+      ([_, clientBlobId]) => clientBlobId
+    );
     this.log(`Checking ${blobNamesToCheck.length} blobs with server`);
     const result = await this.findMissingBlobsDetailed(blobNamesToCheck);
     const missingBlobSet = /* @__PURE__ */ new Set([
@@ -313,7 +366,10 @@ class DirectContext {
     const blobIdMap = /* @__PURE__ */ new Map();
     if (filesToActuallyUpload.length > 0) {
       this.log(`Uploading ${filesToActuallyUpload.length} files to backend`);
-      const uploadedBlobIdMap = await this.batchUploadFiles(filesToActuallyUpload);
+      const uploadedBlobIdMap = await this.batchUploadFiles(
+        filesToActuallyUpload,
+        ctx
+      );
       this.log("Upload complete");
       for (const [clientId, serverId] of uploadedBlobIdMap) {
         blobIdMap.set(clientId, serverId);
@@ -341,8 +397,15 @@ class DirectContext {
   }
   /**
    * Remove paths from the index
+   *
+   * @throws Error if the context was imported from search-only state
    */
   async removeFromIndex(paths) {
+    if (this.isSearchOnly) {
+      throw new Error(
+        "Cannot call removeFromIndex() on a context imported from search-only state. This operation requires full state with blob information. Import from a full state export instead."
+      );
+    }
     return await this.mutex.runExclusive(() => this.doRemoveFromIndex(paths));
   }
   /**
@@ -387,20 +450,24 @@ class DirectContext {
    *
    * This method is serialized via pollingMutex to prevent unbounded concurrent
    * polling requests to the backend.
+   *
+   * @param blobNames - Array of blob names to wait for
+   * @param timeoutMs - Timeout in milliseconds (default: undefined = no timeout)
+   * @param ctx - Progress context for reporting
    */
-  waitForSpecificBlobs(blobNames) {
+  waitForSpecificBlobs(blobNames, timeoutMs, ctx) {
     return this.pollingMutex.runExclusive(async () => {
       if (blobNames.length === 0) {
         this.log("No blobs to wait for");
         return;
       }
+      const timeoutMsg = timeoutMs ? `timeout: ${timeoutMs / 1e3}s` : "no timeout";
       this.log(
-        `Waiting for ${blobNames.length} blobs to be indexed on backend`
+        `Waiting for ${blobNames.length} blobs to be indexed on backend (${timeoutMsg})`
       );
       const initialPollIntervalMs = 3e3;
       const backoffThresholdMs = 6e4;
       const backoffPollIntervalMs = 6e4;
-      const maxWaitTimeMs = 6e5;
       const startTime = Date.now();
       while (true) {
         const result = await this.findMissingBlobsDetailed(blobNames);
@@ -420,6 +487,16 @@ class DirectContext {
           ...result.unknownBlobNames,
           ...result.nonindexedBlobNames
         ];
+        ctx.indexed = blobNames.length - stillPending.length;
+        if (ctx.onProgress) {
+          ctx.onProgress({
+            stage: "indexing",
+            uploaded: ctx.uploaded,
+            indexed: ctx.indexed,
+            total: ctx.total,
+            startedAt: ctx.startedAt
+          });
+        }
         if (stillPending.length === 0) {
           this.log("All blobs indexed successfully");
           return;
@@ -428,9 +505,9 @@ class DirectContext {
         this.log(
           `Still waiting for ${stillPending.length} blobs to be indexed (elapsed: ${Math.round(elapsedMs / 1e3)}s)`
         );
-        if (elapsedMs >= maxWaitTimeMs) {
+        if (timeoutMs !== void 0 && elapsedMs >= timeoutMs) {
           throw new Error(
-            `Indexing timeout: Backend did not finish indexing within ${maxWaitTimeMs / 1e3} seconds`
+            `Indexing timeout: Backend did not finish indexing within ${timeoutMs / 1e3} seconds. You can increase the timeout by passing a 'timeout' option to addToIndex() or waitForIndexing().`
           );
         }
         const pollIntervalMs = elapsedMs < backoffThresholdMs ? initialPollIntervalMs : backoffPollIntervalMs;
@@ -444,12 +521,15 @@ class DirectContext {
    * This method polls the backend until all files that have been added to the index
    * are confirmed to be indexed and searchable.
    *
+   * @param timeout - Timeout in milliseconds (default: undefined = no timeout)
+   * @param onProgress - Optional callback to receive progress updates
    * @returns Promise that resolves when all files are indexed
-   * @throws Error if indexing times out (default: 10 minutes)
+   * @throws Error if indexing times out (only when timeout is specified)
    */
-  async waitForIndexing() {
+  async waitForIndexing(timeout, onProgress) {
     const blobNames = Array.from(this.blobMap.values());
-    await this.waitForSpecificBlobs(blobNames);
+    const ctx = this.createProgressContext(onProgress, blobNames.length, /* @__PURE__ */ new Date());
+    await this.waitForSpecificBlobs(blobNames, timeout, ctx);
   }
   /**
    * Search the codebase using natural language and return formatted results.
@@ -470,11 +550,16 @@ class DirectContext {
    */
   async search(query, options) {
     this.log(`Searching for: "${query}"`);
-    if (this.blobMap.size === 0) {
+    if (!this.isSearchOnly && this.blobMap.size === 0) {
       throw new Error(
         "Index not initialized. Add files to index first using addToIndex()."
       );
     }
+    if (this.isSearchOnly && !this.checkpointId && this.pendingAdded.size === 0) {
+      throw new Error(
+        "Index not initialized. This search-only context has no checkpoint or pending changes."
+      );
+    }
     const blobs = {
       checkpointId: this.checkpointId,
       addedBlobs: Array.from(this.pendingAdded).sort(),
@@ -521,8 +606,40 @@ class DirectContext {
   }
   /**
    * Export the current state to a JSON object
+   *
+   * @param options Export options
+   * @param options.mode Export mode - 'full' (default) includes all blob information,
+   *                     'search-only' excludes blobs array for minimal storage
+   * @returns The exported state object
+   *
+   * @example
+   * ```typescript
+   * // Full export (default) - supports all operations
+   * const fullState = context.export();
+   * const fullState = context.export({ mode: 'full' });
+   *
+   * // Search-only export - much smaller, only supports search operations
+   * const searchState = context.export({ mode: 'search-only' });
+   * ```
    */
-  export() {
+  export(options) {
+    const mode = options?.mode ?? "full";
+    if (mode === "full" && this.isSearchOnly) {
+      throw new Error(
+        "Cannot export as 'full' from a context imported from search-only state. The blob information required for full state is not available. Use export({ mode: 'search-only' }) instead."
+      );
+    }
+    const addedBlobs = Array.from(this.pendingAdded);
+    const deletedBlobs = Array.from(this.pendingDeleted);
+    if (mode === "search-only") {
+      const state2 = {
+        mode: "search-only",
+        checkpointId: this.checkpointId,
+        addedBlobs,
+        deletedBlobs
+      };
+      return state2;
+    }
     const blobs = [];
     for (const [path, serverBlobId] of this.blobMap.entries()) {
       const clientBlobId = this.clientBlobMap.get(path);
@@ -532,26 +649,28 @@ class DirectContext {
         blobs.push([serverBlobId, path]);
       }
     }
-    const addedBlobs = Array.from(this.pendingAdded);
-    const deletedBlobs = Array.from(this.pendingDeleted);
-    return {
+    const state = {
+      mode: "full",
       checkpointId: this.checkpointId,
       addedBlobs,
       deletedBlobs,
       blobs
     };
+    return state;
   }
   /**
    * Internal method to import state from a JSON object
    */
   async doImport(state) {
     return await this.mutex.runExclusive(() => {
+      const mode = "mode" in state ? state.mode : "full";
+      this.isSearchOnly = mode === "search-only";
       this.checkpointId = state.checkpointId;
       this.blobMap.clear();
       this.clientBlobMap.clear();
       this.pendingAdded.clear();
       this.pendingDeleted.clear();
-      if (state.blobs) {
+      if ("blobs" in state && state.blobs) {
         for (const entry of state.blobs) {
           const [serverBlobId, path, clientBlobId] = entry;
           this.blobMap.set(path, serverBlobId);
@@ -565,15 +684,20 @@ class DirectContext {
         this.pendingDeleted = new Set(state.deletedBlobs);
       }
       this.log(
-        `State imported: checkpoint ${this.checkpointId}, ${this.blobMap.size} files, ${this.pendingAdded.size} pending added, ${this.pendingDeleted.size} pending deleted`
+        `State imported (mode: ${mode}): checkpoint ${this.checkpointId}, ${this.blobMap.size} files, ${this.pendingAdded.size} pending added, ${this.pendingDeleted.size} pending deleted`
       );
     });
   }
   /**
    * Export state to a file (Node.js only)
+   *
+   * @param filePath Path to save the state file
+   * @param options Export options
+   * @param options.mode Export mode - 'full' (default) includes all blob information,
+   *                     'search-only' excludes blobs array for minimal storage
    */
-  async exportToFile(filePath) {
-    const state = this.export();
+  async exportToFile(filePath, options) {
+    const state = this.export(options);
     await writeFile(filePath, JSON.stringify(state, null, 2), "utf-8");
     this.log(`State saved to ${filePath}`);
   }

package/dist/context/types.d.ts

@@ -48,7 +48,11 @@ type BlobInfo = {
  * When present, it indicates the server computed a different blob ID than the client.
  * When absent, assume clientBlobId === serverBlobId.
  */
-type BlobEntry = [serverBlobId: string, path: string, clientBlobId?: string];
+type BlobEntry = [
+    serverBlobId: string,
+    path: string,
+    clientBlobId?: string
+];
 /**
  * Blobs payload for API requests
  */
@@ -69,6 +73,75 @@ type IndexingResult = {
     /** Paths that were already uploaded (content unchanged or already on server) */
     alreadyUploaded: string[];
 };
+/**
+ * Progress information for indexing operations
+ */
+type IndexingProgress = {
+    /**
+     * Current stage of the indexing operation
+     * - 'uploading': Files are being uploaded to the backend
+     * - 'indexing': Backend is processing and indexing the uploaded files
+     */
+    stage: "uploading" | "indexing";
+    /**
+     * Number of files uploaded so far
+     */
+    uploaded: number;
+    /**
+     * Number of files indexed so far
+     */
+    indexed: number;
+    /**
+     * Total number of files to upload and index
+     */
+    total: number;
+    /**
+     * Path of the file currently being processed (only available during upload stage)
+     */
+    currentFile?: string;
+    /**
+     * Total bytes uploaded so far (only available during upload stage)
+     */
+    bytesUploaded?: number;
+    /**
+     * When the operation started
+     */
+    startedAt: Date;
+};
+/**
+ * Options for addToIndex operation
+ */
+type AddToIndexOptions = {
+    /**
+     * If true (default), waits for the newly added files to be indexed before returning.
+     * If false, returns immediately after upload completes (indexing continues asynchronously).
+     * Default: true
+     */
+    waitForIndexing?: boolean;
+    /**
+     * Timeout in milliseconds for the indexing operation when waitForIndexing is true.
+     * If the backend does not finish indexing within this time, an error is thrown.
+     * Default: undefined (no timeout - waits indefinitely)
+     *
+     * Set this to a specific value (e.g., 600000 for 10 minutes) if you want to fail fast
+     * in case of backend issues or unexpectedly slow indexing.
+     */
+    timeout?: number;
+    /**
+     * Optional callback to receive progress updates during the indexing operation.
+     * Called periodically with information about the current stage, files uploaded/indexed, etc.
+     *
+     * @example
+     * ```typescript
+     * await context.addToIndex(files, {
+     *   onProgress: (progress) => {
+     *     console.log(`[${progress.stage}] Uploaded: ${progress.uploaded}/${progress.total}, Indexed: ${progress.indexed}/${progress.total}`);
+     *   }
+     * });
+     * ```
+     */
+    onProgress?: (progress: IndexingProgress) => void;
+};
 /**
  * Options for configuring the Direct Context
  */
@@ -91,9 +164,11 @@ type DirectContextOptions = {
     debug?: boolean;
 };
 /**
- * State for Direct Context that can be exported/imported
+ * Full state for Direct Context with all blob information
  */
-type DirectContextState = {
+type FullContextState = {
+    /** Discriminator for state type */
+    mode: "full";
     /** Current checkpoint ID */
     checkpointId?: string;
     /** Array of blob names that have been added (pending checkpoint) */
@@ -103,6 +178,45 @@ type DirectContextState = {
     /** List of blobs as [blobName, path] tuples */
     blobs: BlobEntry[];
 };
+/**
+ * Lightweight search-only state without blob information
+ *
+ * This state format is optimized for search-only use cases and reduces
+ * storage size for large codebases by excluding the blobs array.
+ *
+ * Use this when you only need to search the index and don't need to:
+ * - Add new files to the index
+ * - Remove files from the index
+ * - Get the list of indexed paths
+ */
+type SearchOnlyContextState = {
+    /** Discriminator for state type */
+    mode: "search-only";
+    /** Current checkpoint ID */
+    checkpointId?: string;
+    /** Array of blob names that have been added (pending checkpoint) */
+    addedBlobs: string[];
+    /** Array of blob names that have been deleted (pending checkpoint) */
+    deletedBlobs: string[];
+};
+/**
+ * State for Direct Context that can be exported/imported
+ *
+ * Can be either full state (with blobs array) or search-only state (without blobs array).
+ * For backwards compatibility, states without a mode field are treated as full state.
+ */
+type DirectContextState = FullContextState | SearchOnlyContextState;
+/**
+ * Options for exporting Direct Context state
+ */
+type ExportOptions = {
+    /**
+     * Export mode:
+     * - 'full': Include all blob information (default) - required for addToIndex/removeFromIndex
+     * - 'search-only': Exclude blob array for minimal storage - only supports search operations
+     */
+    mode?: "full" | "search-only";
+};
 /**
  * Options for FileSystem Context (MCP mode)
  */
@@ -115,4 +229,4 @@ type FileSystemContextOptions = {
     debug?: boolean;
 };
 
-export type { BlobEntry, BlobInfo, Blobs, Chunk, DirectContextOptions, DirectContextState, File, FileSystemContextOptions, IndexingResult, SearchResult };
+export type { AddToIndexOptions, BlobEntry, BlobInfo, Blobs, Chunk, DirectContextOptions, DirectContextState, ExportOptions, File, FileSystemContextOptions, FullContextState, IndexingProgress, IndexingResult, SearchOnlyContextState, SearchResult };

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { DirectContext } from './context/direct-context.js';
 export { FileSystemContext } from './context/filesystem-context.js';
 export { APIError } from './context/internal/api-client.js';
 export { BlobTooLargeError } from './context/internal/blob-name-calculator.js';
-export { BlobEntry, BlobInfo, Blobs, DirectContextOptions, DirectContextState, File, FileSystemContextOptions, IndexingResult } from './context/types.js';
+export { AddToIndexOptions, BlobEntry, BlobInfo, Blobs, DirectContextOptions, DirectContextState, ExportOptions, File, FileSystemContextOptions, FullContextState, IndexingProgress, IndexingResult, SearchOnlyContextState } from './context/types.js';
 import '@agentclientprotocol/sdk';
 import 'ai';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augmentcode/auggie-sdk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "TypeScript SDK for Auggie",
   "type": "module",
   "main": "./dist/index.js",