@probelabs/probe 0.6.0-rc231 → 0.6.0-rc232

package/build/agent/ProbeAgent.js

@@ -357,6 +357,10 @@ export class ProbeAgent {
     // Each ProbeAgent instance has its own limits, not shared globally
     this.delegationManager = new DelegationManager();
 
+    // Optional global concurrency limiter shared across all ProbeAgent instances.
+    // When set, every AI API call acquires a slot before calling the provider.
+    this.concurrencyLimiter = options.concurrencyLimiter || null;
+
     // Request timeout configuration (default 2 minutes)
     // Validates env var to prevent NaN or unreasonable values
     this.requestTimeout = options.requestTimeout ?? (() => {
@@ -824,6 +828,7 @@ export class ProbeAgent {
       provider: this.clientApiProvider,
       model: this.clientApiModel,
       delegationManager: this.delegationManager,  // Per-instance delegation limits
+      concurrencyLimiter: this.concurrencyLimiter,  // Global AI concurrency limiter
       isToolAllowed
     };
 
@@ -1363,6 +1368,16 @@ export class ProbeAgent {
    * @private
    */
   async streamTextWithRetryAndFallback(options) {
+    // Acquire global concurrency slot if limiter is configured
+    const limiter = this.concurrencyLimiter;
+    if (limiter) {
+      await limiter.acquire(null);
+      if (this.debug) {
+        const stats = limiter.getStats();
+        console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+      }
+    }
+
     // Create AbortController for overall operation timeout
     const controller = new AbortController();
     const timeoutState = { timeoutId: null };
@@ -1382,12 +1397,10 @@ export class ProbeAgent {
       const useClaudeCode = this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true';
       const useCodex = this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true';
 
+      let result;
       if (useClaudeCode || useCodex) {
         try {
-          const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-          if (result) {
-            return result;
-          }
+          result = await this._tryEngineStreamPath(options, controller, timeoutState);
         } catch (error) {
           if (this.debug) {
             const engineType = useClaudeCode ? 'Claude Code' : 'Codex';
@@ -1397,8 +1410,43 @@ export class ProbeAgent {
         }
       }
 
-      // Use Vercel AI SDK with retry/fallback
-      return await this._executeWithVercelProvider(options, controller);
+      if (!result) {
+        // Use Vercel AI SDK with retry/fallback
+        result = await this._executeWithVercelProvider(options, controller);
+      }
+
+      // Wrap textStream so limiter slot is held until stream completes
+      if (limiter && result.textStream) {
+        const originalStream = result.textStream;
+        const debug = this.debug;
+        result.textStream = (async function* () {
+          try {
+            for await (const chunk of originalStream) {
+              yield chunk;
+            }
+          } finally {
+            limiter.release(null);
+            if (debug) {
+              const stats = limiter.getStats();
+              console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+            }
+          }
+        })();
+      } else if (limiter) {
+        // No textStream (shouldn't happen, but release just in case)
+        limiter.release(null);
+      }
+
+      return result;
+    } catch (error) {
+      // Release on error if limiter was acquired
+      if (limiter) {
+        limiter.release(null);
+        if (this.debug) {
+          console.log(`[DEBUG] Released global AI concurrency slot on error`);
+        }
+      }
+      throw error;
     } finally {
       // Clean up timeout (for non-engine paths; engine paths clean up in the generator)
       if (timeoutState.timeoutId) {

package/build/agent/index.js

@@ -3859,8 +3859,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -3936,8 +3938,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -4034,10 +4038,10 @@ var init_delegate = __esm({
     "use strict";
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];
@@ -70572,6 +70576,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -70948,6 +70953,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -71369,6 +71376,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -71382,12 +71397,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -71395,7 +71408,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);

package/build/delegate.js

@@ -19,11 +19,14 @@ import { ProbeAgent } from './agent/ProbeAgent.js';
  * - For long-running processes, periodic cleanup of stale sessions may be needed
  */
 class DelegationManager {
-	constructor() {
-		this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
-		this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
+	constructor(options = {}) {
+		this.maxConcurrent = options.maxConcurrent
+			?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
+		this.maxPerSession = options.maxPerSession
+			?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
 		// Default queue timeout: 60 seconds. Set DELEGATION_QUEUE_TIMEOUT=0 to disable.
-		this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
+		this.defaultQueueTimeout = options.queueTimeout
+			?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
 
 		// Track delegations per session with timestamp for potential TTL cleanup
 		// Map<string, { count: number, lastUpdated: number }>
@@ -353,6 +356,7 @@ const DEFAULT_DELEGATE_TIMEOUT = parseInt(process.env.DELEGATE_TIMEOUT, 10) || 3
  * @param {boolean} [options.enableMcp=false] - Enable MCP tool integration (inherited from parent)
  * @param {Object} [options.mcpConfig] - MCP configuration object (inherited from parent)
  * @param {string} [options.mcpConfigPath] - Path to MCP configuration file (inherited from parent)
+ * @param {Object} [options.concurrencyLimiter=null] - Global AI concurrency limiter (DelegationManager instance)
  * @returns {Promise<string>} The response from the delegate agent
  */
 export async function delegate({
@@ -379,7 +383,8 @@ export async function delegate({
 	enableMcp = false,
 	mcpConfig = null,
 	mcpConfigPath = null,
-	delegationManager = null  // Optional per-instance manager, falls back to default singleton
+	delegationManager = null,  // Optional per-instance manager, falls back to default singleton
+	concurrencyLimiter = null  // Optional global AI concurrency limiter
 }) {
 	if (!task || typeof task !== 'string') {
 		throw new Error('Task parameter is required and must be a string');
@@ -464,7 +469,8 @@ export async function delegate({
 			enableTasks, // Inherit from parent (subagent gets isolated TaskManager)
 			enableMcp,   // Inherit from parent (subagent creates own MCPXmlBridge)
 			mcpConfig,   // Inherit from parent
-			mcpConfigPath // Inherit from parent
+			mcpConfigPath, // Inherit from parent
+			concurrencyLimiter // Inherit global AI concurrency limiter
 		});
 
 		if (debug) {

package/cjs/agent/ProbeAgent.cjs

@@ -30969,8 +30969,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -31046,8 +31048,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -31145,10 +31149,10 @@ var init_delegate = __esm({
     import_crypto2 = require("crypto");
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];
@@ -97249,6 +97253,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -97625,6 +97630,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -98046,6 +98053,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -98059,12 +98074,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error2) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -98072,7 +98085,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error2) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error2;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);

package/cjs/index.cjs

@@ -93982,6 +93982,7 @@ var init_ProbeAgent = __esm({
         this.enableTasks = !!options.enableTasks;
         this.taskManager = null;
         this.delegationManager = new DelegationManager();
+        this.concurrencyLimiter = options.concurrencyLimiter || null;
         this.requestTimeout = options.requestTimeout ?? (() => {
           if (process.env.REQUEST_TIMEOUT) {
             const parsed = parseInt(process.env.REQUEST_TIMEOUT, 10);
@@ -94358,6 +94359,8 @@ var init_ProbeAgent = __esm({
           model: this.clientApiModel,
           delegationManager: this.delegationManager,
           // Per-instance delegation limits
+          concurrencyLimiter: this.concurrencyLimiter,
+          // Global AI concurrency limiter
           isToolAllowed
         };
         const baseTools = createTools(configOptions);
@@ -94779,6 +94782,14 @@ var init_ProbeAgent = __esm({
        * @private
        */
       async streamTextWithRetryAndFallback(options) {
+        const limiter = this.concurrencyLimiter;
+        if (limiter) {
+          await limiter.acquire(null);
+          if (this.debug) {
+            const stats = limiter.getStats();
+            console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+          }
+        }
         const controller = new AbortController();
         const timeoutState = { timeoutId: null };
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
@@ -94792,12 +94803,10 @@ var init_ProbeAgent = __esm({
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
           const useCodex = this.clientApiProvider === "codex" || process.env.USE_CODEX === "true";
+          let result;
           if (useClaudeCode || useCodex) {
             try {
-              const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-              if (result) {
-                return result;
-              }
+              result = await this._tryEngineStreamPath(options, controller, timeoutState);
             } catch (error2) {
               if (this.debug) {
                 const engineType = useClaudeCode ? "Claude Code" : "Codex";
@@ -94805,7 +94814,37 @@ var init_ProbeAgent = __esm({
               }
             }
           }
-          return await this._executeWithVercelProvider(options, controller);
+          if (!result) {
+            result = await this._executeWithVercelProvider(options, controller);
+          }
+          if (limiter && result.textStream) {
+            const originalStream = result.textStream;
+            const debug = this.debug;
+            result.textStream = (async function* () {
+              try {
+                for await (const chunk of originalStream) {
+                  yield chunk;
+                }
+              } finally {
+                limiter.release(null);
+                if (debug) {
+                  const stats = limiter.getStats();
+                  console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+                }
+              }
+            })();
+          } else if (limiter) {
+            limiter.release(null);
+          }
+          return result;
+        } catch (error2) {
+          if (limiter) {
+            limiter.release(null);
+            if (this.debug) {
+              console.log(`[DEBUG] Released global AI concurrency slot on error`);
+            }
+          }
+          throw error2;
         } finally {
           if (timeoutState.timeoutId) {
             clearTimeout(timeoutState.timeoutId);
@@ -97639,8 +97678,10 @@ async function delegate({
   enableMcp = false,
   mcpConfig = null,
   mcpConfigPath = null,
-  delegationManager = null
+  delegationManager = null,
   // Optional per-instance manager, falls back to default singleton
+  concurrencyLimiter = null
+  // Optional global AI concurrency limiter
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -97716,8 +97757,10 @@ async function delegate({
       // Inherit from parent (subagent creates own MCPXmlBridge)
       mcpConfig,
       // Inherit from parent
-      mcpConfigPath
+      mcpConfigPath,
       // Inherit from parent
+      concurrencyLimiter
+      // Inherit global AI concurrency limiter
     });
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
@@ -97815,10 +97858,10 @@ var init_delegate = __esm({
     import_crypto9 = require("crypto");
     init_ProbeAgent();
     DelegationManager = class {
-      constructor() {
-        this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
-        this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
-        this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
+      constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || "3", 10);
+        this.maxPerSession = options.maxPerSession ?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || "10", 10);
+        this.defaultQueueTimeout = options.queueTimeout ?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || "60000", 10);
         this.sessionDelegations = /* @__PURE__ */ new Map();
         this.globalActive = 0;
         this.waitQueue = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc231",
+  "version": "0.6.0-rc232",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/agent/ProbeAgent.js

@@ -357,6 +357,10 @@ export class ProbeAgent {
     // Each ProbeAgent instance has its own limits, not shared globally
     this.delegationManager = new DelegationManager();
 
+    // Optional global concurrency limiter shared across all ProbeAgent instances.
+    // When set, every AI API call acquires a slot before calling the provider.
+    this.concurrencyLimiter = options.concurrencyLimiter || null;
+
     // Request timeout configuration (default 2 minutes)
     // Validates env var to prevent NaN or unreasonable values
     this.requestTimeout = options.requestTimeout ?? (() => {
@@ -824,6 +828,7 @@ export class ProbeAgent {
       provider: this.clientApiProvider,
       model: this.clientApiModel,
       delegationManager: this.delegationManager,  // Per-instance delegation limits
+      concurrencyLimiter: this.concurrencyLimiter,  // Global AI concurrency limiter
       isToolAllowed
     };
 
@@ -1363,6 +1368,16 @@ export class ProbeAgent {
    * @private
    */
   async streamTextWithRetryAndFallback(options) {
+    // Acquire global concurrency slot if limiter is configured
+    const limiter = this.concurrencyLimiter;
+    if (limiter) {
+      await limiter.acquire(null);
+      if (this.debug) {
+        const stats = limiter.getStats();
+        console.log(`[DEBUG] Acquired global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+      }
+    }
+
     // Create AbortController for overall operation timeout
     const controller = new AbortController();
     const timeoutState = { timeoutId: null };
@@ -1382,12 +1397,10 @@ export class ProbeAgent {
       const useClaudeCode = this.clientApiProvider === 'claude-code' || process.env.USE_CLAUDE_CODE === 'true';
       const useCodex = this.clientApiProvider === 'codex' || process.env.USE_CODEX === 'true';
 
+      let result;
       if (useClaudeCode || useCodex) {
         try {
-          const result = await this._tryEngineStreamPath(options, controller, timeoutState);
-          if (result) {
-            return result;
-          }
+          result = await this._tryEngineStreamPath(options, controller, timeoutState);
         } catch (error) {
           if (this.debug) {
             const engineType = useClaudeCode ? 'Claude Code' : 'Codex';
@@ -1397,8 +1410,43 @@ export class ProbeAgent {
         }
       }
 
-      // Use Vercel AI SDK with retry/fallback
-      return await this._executeWithVercelProvider(options, controller);
+      if (!result) {
+        // Use Vercel AI SDK with retry/fallback
+        result = await this._executeWithVercelProvider(options, controller);
+      }
+
+      // Wrap textStream so limiter slot is held until stream completes
+      if (limiter && result.textStream) {
+        const originalStream = result.textStream;
+        const debug = this.debug;
+        result.textStream = (async function* () {
+          try {
+            for await (const chunk of originalStream) {
+              yield chunk;
+            }
+          } finally {
+            limiter.release(null);
+            if (debug) {
+              const stats = limiter.getStats();
+              console.log(`[DEBUG] Released global AI concurrency slot (${stats.globalActive}/${stats.maxConcurrent}, queue: ${stats.queueSize})`);
+            }
+          }
+        })();
+      } else if (limiter) {
+        // No textStream (shouldn't happen, but release just in case)
+        limiter.release(null);
+      }
+
+      return result;
+    } catch (error) {
+      // Release on error if limiter was acquired
+      if (limiter) {
+        limiter.release(null);
+        if (this.debug) {
+          console.log(`[DEBUG] Released global AI concurrency slot on error`);
+        }
+      }
+      throw error;
     } finally {
       // Clean up timeout (for non-engine paths; engine paths clean up in the generator)
       if (timeoutState.timeoutId) {

package/src/delegate.js

@@ -19,11 +19,14 @@ import { ProbeAgent } from './agent/ProbeAgent.js';
  * - For long-running processes, periodic cleanup of stale sessions may be needed
  */
 class DelegationManager {
-	constructor() {
-		this.maxConcurrent = parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
-		this.maxPerSession = parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
+	constructor(options = {}) {
+		this.maxConcurrent = options.maxConcurrent
+			?? parseInt(process.env.MAX_CONCURRENT_DELEGATIONS || '3', 10);
+		this.maxPerSession = options.maxPerSession
+			?? parseInt(process.env.MAX_DELEGATIONS_PER_SESSION || '10', 10);
 		// Default queue timeout: 60 seconds. Set DELEGATION_QUEUE_TIMEOUT=0 to disable.
-		this.defaultQueueTimeout = parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
+		this.defaultQueueTimeout = options.queueTimeout
+			?? parseInt(process.env.DELEGATION_QUEUE_TIMEOUT || '60000', 10);
 
 		// Track delegations per session with timestamp for potential TTL cleanup
 		// Map<string, { count: number, lastUpdated: number }>
@@ -353,6 +356,7 @@ const DEFAULT_DELEGATE_TIMEOUT = parseInt(process.env.DELEGATE_TIMEOUT, 10) || 3
  * @param {boolean} [options.enableMcp=false] - Enable MCP tool integration (inherited from parent)
  * @param {Object} [options.mcpConfig] - MCP configuration object (inherited from parent)
  * @param {string} [options.mcpConfigPath] - Path to MCP configuration file (inherited from parent)
+ * @param {Object} [options.concurrencyLimiter=null] - Global AI concurrency limiter (DelegationManager instance)
  * @returns {Promise<string>} The response from the delegate agent
  */
 export async function delegate({
@@ -379,7 +383,8 @@ export async function delegate({
 	enableMcp = false,
 	mcpConfig = null,
 	mcpConfigPath = null,
-	delegationManager = null  // Optional per-instance manager, falls back to default singleton
+	delegationManager = null,  // Optional per-instance manager, falls back to default singleton
+	concurrencyLimiter = null  // Optional global AI concurrency limiter
 }) {
 	if (!task || typeof task !== 'string') {
 		throw new Error('Task parameter is required and must be a string');
@@ -464,7 +469,8 @@ export async function delegate({
 			enableTasks, // Inherit from parent (subagent gets isolated TaskManager)
 			enableMcp,   // Inherit from parent (subagent creates own MCPXmlBridge)
 			mcpConfig,   // Inherit from parent
-			mcpConfigPath // Inherit from parent
+			mcpConfigPath, // Inherit from parent
+			concurrencyLimiter // Inherit global AI concurrency limiter
 		});
 
 		if (debug) {