@probelabs/probe 0.6.0-rc294 → 0.6.0-rc296

package/cjs/index.cjs

@@ -27051,14 +27051,64 @@ function detectStuckResponse(response) {
   }
   return false;
 }
+function splitQuotedString(input) {
+  const tokens = [];
+  let current2 = "";
+  let inQuote = null;
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i];
+    if (inQuote) {
+      if (ch === "\\" && i + 1 < input.length) {
+        current2 += input[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === inQuote) {
+        inQuote = null;
+        i++;
+        continue;
+      }
+      current2 += ch;
+      i++;
+    } else {
+      if (ch === '"' || ch === "'") {
+        inQuote = ch;
+        i++;
+        continue;
+      }
+      if (/[\s,]/.test(ch)) {
+        if (current2.length > 0) {
+          tokens.push(current2);
+          current2 = "";
+        }
+        i++;
+        continue;
+      }
+      current2 += ch;
+      i++;
+    }
+  }
+  if (current2.length > 0) {
+    tokens.push(current2);
+  }
+  return tokens;
+}
 function parseTargets(targets) {
   if (!targets || typeof targets !== "string") {
     return [];
   }
-  return targets.split(/[\s,]+/).filter((f) => f.length > 0);
+  return splitQuotedString(targets);
 }
 function parseAndResolvePaths(pathStr, cwd) {
   if (!pathStr) return [];
+  if (/["']/.test(pathStr)) {
+    const paths2 = splitQuotedString(pathStr);
+    return paths2.map((p) => {
+      if ((0, import_path5.isAbsolute)(p)) return p;
+      return cwd ? (0, import_path5.resolve)(cwd, p) : p;
+    });
+  }
   let paths = pathStr.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
   paths = paths.flatMap((p) => {
     if (!/\s/.test(p)) return [p];
@@ -27068,9 +27118,7 @@ function parseAndResolvePaths(pathStr, cwd) {
     return allLookLikePaths ? parts : [p];
   });
   return paths.map((p) => {
-    if ((0, import_path5.isAbsolute)(p)) {
-      return p;
-    }
+    if ((0, import_path5.isAbsolute)(p)) return p;
     return cwd ? (0, import_path5.resolve)(cwd, p) : p;
   });
 }
@@ -27103,7 +27151,7 @@ var init_common = __esm({
     searchSchema = external_exports2.object({
       query: external_exports2.string().describe("Search query \u2014 natural language questions or Elasticsearch-style keywords both work. For keywords: use quotes for exact phrases, AND/OR for boolean logic, - for negation. Probe handles stemming and camelCase/snake_case splitting automatically, so do NOT try case or style variations of the same keyword."),
       path: external_exports2.string().optional().default(".").describe('Path to search in. For dependencies use "go:github.com/owner/repo", "js:package_name", or "rust:cargo_name" etc.'),
-      exact: external_exports2.boolean().optional().default(false).describe('Default (false) enables stemming and keyword splitting for exploratory search - "getUserData" matches "get", "user", "data", etc. Set true for precise symbol lookup where "getUserData" matches only "getUserData". Use true when you know the exact symbol name.'),
+      exact: external_exports2.boolean().optional().default(false).describe(`Default (false) enables stemming and keyword splitting for exploratory search - "getUserData" matches "get", "user", "data", etc. Set true for precise symbol lookup OR when searching for strings with punctuation/quotes/empty values (e.g. 'description: ""' \u2014 BM25 strips punctuation so exact=true is required for literal matching). Use true when you know the exact symbol name or need literal string matching.`),
       maxTokens: external_exports2.number().nullable().optional().describe("Maximum tokens to return. Default is 20000. Set to null for unlimited results."),
       session: external_exports2.string().optional().describe("Session ID for result caching and pagination. Pass the session ID from a previous search to get additional results (next page). Results already shown in a session are automatically excluded. Omit for a fresh search."),
       nextPage: external_exports2.boolean().optional().default(false).describe("Set to true when requesting the next page of results. Requires passing the same session ID from the previous search output.")
@@ -73542,6 +73590,9 @@ function isMethodAllowed(methodName, allowedMethods, blockedMethods) {
 }
 function createTransport(serverConfig) {
   const { transport, command, args, url: url2, env } = serverConfig;
+  if (serverConfig.transportInstance) {
+    return serverConfig.transportInstance;
+  }
   switch (transport) {
     case "stdio":
       return new import_stdio.StdioClientTransport({
@@ -73904,6 +73955,53 @@ var init_client = __esm({
           throw error40;
         }
       }
+      /**
+       * Call graceful_stop on all MCP servers that expose it.
+       * This signals agent-type MCP servers to wrap up their work.
+       * @returns {Promise<Array<{server: string, success: boolean, error?: string}>>}
+       */
+      async callGracefulStopAll() {
+        const results = [];
+        for (const [serverName, clientInfo] of this.clients) {
+          const qualifiedName = `${serverName}_graceful_stop`;
+          if (this.tools.has(qualifiedName)) {
+            if (this.debug) {
+              console.log(`[DEBUG] MCP callGracefulStopAll: calling graceful_stop on server "${serverName}"`);
+            }
+            try {
+              const timeoutMs = 5e3;
+              const timeoutPromise = new Promise(
+                (_, reject2) => setTimeout(() => reject2(new Error("graceful_stop timeout")), timeoutMs)
+              );
+              await Promise.race([
+                clientInfo.client.callTool({ name: "graceful_stop", arguments: {} }, void 0, { timeout: timeoutMs }),
+                timeoutPromise
+              ]);
+              results.push({ server: serverName, success: true });
+              if (this.debug) {
+                console.log(`[DEBUG] MCP callGracefulStopAll: server "${serverName}" acknowledged graceful_stop`);
+              }
+            } catch (e) {
+              results.push({ server: serverName, success: false, error: e.message });
+              if (this.debug) {
+                console.log(`[DEBUG] MCP callGracefulStopAll: server "${serverName}" graceful_stop failed: ${e.message}`);
+              }
+            }
+          }
+        }
+        if (this.debug) {
+          const withStop = results.length;
+          const total = this.clients.size;
+          console.log(`[DEBUG] MCP callGracefulStopAll: ${withStop}/${total} servers had graceful_stop tool`);
+        }
+        this.recordMcpEvent("graceful_stop.sweep_completed", {
+          servers_total: this.clients.size,
+          servers_with_graceful_stop: results.length,
+          servers_acknowledged: results.filter((r) => r.success).length,
+          servers_failed: results.filter((r) => !r.success).length
+        });
+        return results;
+      }
       /**
        * Get all available tools with their schemas
        * @returns {Object} Map of tool name to tool definition
@@ -73931,10 +74029,29 @@ var init_client = __esm({
             inputSchema: tool6.inputSchema,
             execute: async (args) => {
               const result = await this.callTool(name15, args);
-              if (result.content && result.content[0]) {
-                return result.content[0].text;
+              if (!result.content || !result.content[0]) {
+                return JSON.stringify(result);
+              }
+              const hasImage = result.content.some((block) => block.type === "image");
+              if (hasImage) {
+                return { _mcpContent: result.content };
               }
-              return JSON.stringify(result);
+              return result.content[0].text;
+            },
+            // Convert MCP content blocks (including images) to Vercel AI SDK format
+            toModelOutput: ({ output }) => {
+              if (output && typeof output === "object" && output._mcpContent) {
+                const parts = [];
+                for (const block of output._mcpContent) {
+                  if (block.type === "text") {
+                    parts.push({ type: "text", text: block.text });
+                  } else if (block.type === "image") {
+                    parts.push({ type: "image-data", data: block.data, mediaType: block.mimeType });
+                  }
+                }
+                return { type: "content", value: parts };
+              }
+              return { type: "text", value: typeof output === "string" ? output : JSON.stringify(output) };
             }
           };
         }
@@ -74114,6 +74231,16 @@ var init_xmlBridge = __esm({
       isMcpTool(toolName) {
         return toolName in this.mcpTools;
       }
+      /**
+       * Call graceful_stop on all MCP servers that expose it.
+       * @returns {Promise<Array>}
+       */
+      async callGracefulStopAll() {
+        if (this.mcpManager) {
+          return this.mcpManager.callGracefulStopAll();
+        }
+        return [];
+      }
       /**
        * Clean up MCP connections
        */
@@ -96673,6 +96800,7 @@ var init_ProbeAgent = __esm({
         this.debug = options.debug || process.env.DEBUG === "1";
         this.cancelled = false;
         this._abortController = new AbortController();
+        this._activeSubagents = /* @__PURE__ */ new Map();
         this.tracer = options.tracer || null;
         this.outline = !!options.outline;
         this.searchDelegate = options.searchDelegate !== void 0 ? !!options.searchDelegate : true;
@@ -96781,6 +96909,35 @@ var init_ProbeAgent = __esm({
         if (this.debug) {
           console.log(`[DEBUG] Max operation timeout: ${this.maxOperationTimeout}ms`);
         }
+        this.timeoutBehavior = options.timeoutBehavior ?? (() => {
+          const val = process.env.TIMEOUT_BEHAVIOR;
+          if (val === "hard") return "hard";
+          if (val === "negotiated") return "negotiated";
+          return "graceful";
+        })();
+        this.gracefulTimeoutBonusSteps = options.gracefulTimeoutBonusSteps ?? (() => {
+          const parsed = parseInt(process.env.GRACEFUL_TIMEOUT_BONUS_STEPS, 10);
+          return isNaN(parsed) || parsed < 1 || parsed > 20 ? 4 : parsed;
+        })();
+        this.negotiatedTimeoutBudget = options.negotiatedTimeoutBudget ?? (() => {
+          const parsed = parseInt(process.env.NEGOTIATED_TIMEOUT_BUDGET, 10);
+          return isNaN(parsed) || parsed < 6e4 || parsed > 72e5 ? 18e5 : parsed;
+        })();
+        this.negotiatedTimeoutMaxRequests = options.negotiatedTimeoutMaxRequests ?? (() => {
+          const parsed = parseInt(process.env.NEGOTIATED_TIMEOUT_MAX_REQUESTS, 10);
+          return isNaN(parsed) || parsed < 1 || parsed > 10 ? 3 : parsed;
+        })();
+        this.negotiatedTimeoutMaxPerRequest = options.negotiatedTimeoutMaxPerRequest ?? (() => {
+          const parsed = parseInt(process.env.NEGOTIATED_TIMEOUT_MAX_PER_REQUEST, 10);
+          return isNaN(parsed) || parsed < 6e4 || parsed > 36e5 ? 6e5 : parsed;
+        })();
+        this.gracefulStopDeadline = options.gracefulStopDeadline ?? (() => {
+          const parsed = parseInt(process.env.GRACEFUL_STOP_DEADLINE, 10);
+          return isNaN(parsed) || parsed < 5e3 || parsed > 3e5 ? 45e3 : parsed;
+        })();
+        if (this.debug) {
+          console.log(`[DEBUG] Timeout behavior: ${this.timeoutBehavior}, bonus steps: ${this.gracefulTimeoutBonusSteps}, graceful stop deadline: ${this.gracefulStopDeadline}ms`);
+        }
         this.retryConfig = options.retry || {};
         this.retryManager = null;
         this.fallbackConfig = options.fallback || null;
@@ -97131,6 +97288,18 @@ var init_ProbeAgent = __esm({
           // Per-instance delegation limits
           parentAbortSignal: this._abortController.signal,
           // Propagate cancellation to delegations
+          // Timeout settings for delegate subagents to inherit
+          timeoutBehavior: this.timeoutBehavior,
+          maxOperationTimeout: this.maxOperationTimeout,
+          requestTimeout: this.requestTimeout,
+          gracefulTimeoutBonusSteps: this.gracefulTimeoutBonusSteps,
+          negotiatedTimeoutBudget: this.negotiatedTimeoutBudget,
+          negotiatedTimeoutMaxRequests: this.negotiatedTimeoutMaxRequests,
+          negotiatedTimeoutMaxPerRequest: this.negotiatedTimeoutMaxPerRequest,
+          parentOperationStartTime: this._operationStartTime,
+          // For remaining budget calculation
+          onSubagentCreated: (sid, subagent) => this._registerSubagent(sid, subagent),
+          onSubagentCompleted: (sid) => this._unregisterSubagent(sid),
           outputBuffer: this._outputBuffer,
           concurrencyLimiter: this.concurrencyLimiter,
           // Global AI concurrency limiter
@@ -97714,12 +97883,16 @@ var init_ProbeAgent = __esm({
           }, { once: true });
         }
         if (this.maxOperationTimeout && this.maxOperationTimeout > 0) {
-          timeoutState.timeoutId = setTimeout(() => {
-            controller.abort();
-            if (this.debug) {
-              console.log(`[DEBUG] Operation timed out after ${this.maxOperationTimeout}ms (max operation timeout)`);
-            }
-          }, this.maxOperationTimeout);
+          const gts = this._gracefulTimeoutState;
+          if ((this.timeoutBehavior === "graceful" || this.timeoutBehavior === "negotiated") && gts) {
+          } else {
+            timeoutState.timeoutId = setTimeout(() => {
+              controller.abort();
+              if (this.debug) {
+                console.log(`[DEBUG] Operation timed out after ${this.maxOperationTimeout}ms (max operation timeout)`);
+              }
+            }, this.maxOperationTimeout);
+          }
         }
         try {
           const useClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
@@ -99098,6 +99271,7 @@ You are working with a workspace. Available paths: ${workspaceDesc}
         } else {
           options = schemaOrOptions || {};
         }
+        this._operationStartTime = Date.now();
         try {
           const oldHistoryLength = this.history.length;
           if (this._outputBuffer && !options?._schemaFormatted && !options?._completionPromptProcessed) {
@@ -99178,7 +99352,10 @@ You are working with a workspace. Available paths: ${workspaceDesc}
             }
           }
           let currentIteration = 0;
-          let finalResult = "I was unable to complete your request due to reaching the maximum number of tool iterations.";
+          let finalResult = null;
+          const DEFAULT_MAX_ITER_MSG = "I was unable to complete your request due to reaching the maximum number of tool iterations.";
+          const _toolCallLog = [];
+          let abortSummaryTaken = false;
           const baseMaxIterations = options._maxIterationsOverride || this.maxIterations || MAX_TOOL_ITERATIONS;
           const maxIterations = options._maxIterationsOverride ? baseMaxIterations : options.schema ? baseMaxIterations + 4 : baseMaxIterations;
           const isClaudeCode = this.clientApiProvider === "claude-code" || process.env.USE_CLAUDE_CODE === "true";
@@ -99310,6 +99487,228 @@ You are working with a workspace. Available paths: ${workspaceDesc}
           }
           let completionPromptInjected = false;
           let preCompletionResult = null;
+          const gracefulTimeoutState = {
+            triggered: false,
+            // Set to true when soft timeout fires
+            bonusStepsUsed: 0,
+            // Steps taken after soft timeout
+            bonusStepsMax: this.gracefulTimeoutBonusSteps
+          };
+          this._gracefulTimeoutState = gracefulTimeoutState;
+          const negotiatedTimeoutState = {
+            extensionsUsed: 0,
+            totalExtraTimeMs: 0,
+            softTimeoutId: null,
+            hardAbortTimeoutId: null,
+            maxRequests: this.negotiatedTimeoutMaxRequests,
+            maxPerRequestMs: this.negotiatedTimeoutMaxPerRequest,
+            budgetMs: this.negotiatedTimeoutBudget,
+            observerRunning: false,
+            // true while observer LLM call is in flight
+            extensionMessage: null,
+            // message to show in prepareStep after extension granted
+            startTime: Date.now()
+          };
+          this._negotiatedTimeoutState = negotiatedTimeoutState;
+          const activeTools = /* @__PURE__ */ new Map();
+          this._activeTools = activeTools;
+          const onToolCall = (event) => {
+            const key = event.toolCallId || `${event.name}:${JSON.stringify(event.args || {}).slice(0, 100)}`;
+            if (event.status === "started") {
+              activeTools.set(key, {
+                name: event.name,
+                args: event.args,
+                startedAt: event.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+              });
+            } else if (event.status === "completed" || event.status === "error") {
+              activeTools.delete(key);
+            }
+          };
+          this.events.on("toolCall", onToolCall);
+          const runTimeoutObserver = async () => {
+            if (negotiatedTimeoutState.observerRunning) return;
+            negotiatedTimeoutState.observerRunning = true;
+            const remainingRequests = negotiatedTimeoutState.maxRequests - negotiatedTimeoutState.extensionsUsed;
+            const remainingBudgetMs = negotiatedTimeoutState.budgetMs - negotiatedTimeoutState.totalExtraTimeMs;
+            const maxPerReqMin = Math.round(negotiatedTimeoutState.maxPerRequestMs / 6e4);
+            const elapsedMin = Math.round((Date.now() - negotiatedTimeoutState.startTime) / 6e4);
+            if (remainingRequests <= 0 || remainingBudgetMs <= 0) {
+              if (this.debug) {
+                console.log(`[DEBUG] Timeout observer: no extensions/budget remaining \u2014 aborting in-flight tools and triggering graceful wind-down`);
+              }
+              if (this.tracer) {
+                this.tracer.addEvent("negotiated_timeout.observer_exhausted", {
+                  extensions_used: negotiatedTimeoutState.extensionsUsed,
+                  max_requests: negotiatedTimeoutState.maxRequests,
+                  total_extra_time_ms: negotiatedTimeoutState.totalExtraTimeMs,
+                  budget_ms: negotiatedTimeoutState.budgetMs,
+                  elapsed_min: elapsedMin,
+                  active_tools: Array.from(activeTools.values()).map((t) => t.name)
+                });
+              }
+              await this._initiateGracefulStop(gracefulTimeoutState, "budget/extensions exhausted");
+              negotiatedTimeoutState.observerRunning = false;
+              return;
+            }
+            const activeToolsList = Array.from(activeTools.values());
+            const now = Date.now();
+            const formatDuration = (ms) => {
+              const totalSec = Math.round(ms / 1e3);
+              if (totalSec < 60) return `${totalSec}s`;
+              const min = Math.floor(totalSec / 60);
+              const sec = totalSec % 60;
+              if (min < 60) return `${min}m ${sec}s`;
+              const hr = Math.floor(min / 60);
+              const remainMin = min % 60;
+              return `${hr}h ${remainMin}m`;
+            };
+            const activeToolsDesc = activeToolsList.length > 0 ? activeToolsList.map((t) => {
+              const runningForMs = now - new Date(t.startedAt).getTime();
+              return `- ${t.name}(${JSON.stringify(t.args || {}).slice(0, 200)}) \u2014 running for ${formatDuration(runningForMs)}`;
+            }).join("\n") : "(none currently running)";
+            const recentHistory = this.history.slice(-6).map((msg) => {
+              const content = typeof msg.content === "string" ? msg.content.slice(0, 300) : JSON.stringify(msg.content).slice(0, 300);
+              return `[${msg.role}]: ${content}`;
+            }).join("\n");
+            const observerPrompt = `You are a timeout observer for an AI coding agent. The agent has been working for ${elapsedMin} minute(s) and has reached its time limit.
+
+## Recent Conversation
+${recentHistory || "(no history yet)"}
+
+## Currently Running Tools
+${activeToolsDesc}
+
+## Budget
+- Extensions used: ${negotiatedTimeoutState.extensionsUsed}/${negotiatedTimeoutState.maxRequests}
+- Time budget remaining: ${Math.round(remainingBudgetMs / 6e4)} minutes
+- Max per extension: ${maxPerReqMin} minutes
+
+Decide whether the agent should get more time. EXTEND if:
+- Tools are actively running (especially delegates or complex analysis) \u2014 they need time to finish
+- The agent is making clear progress on a complex task
+- New information is being gathered that will improve the final answer
+
+DO NOT EXTEND if:
+- The agent appears stuck in a loop (repeating the same tool calls or getting the same errors)
+- The conversation shows the agent retrying failed operations without changing approach
+- The agent has enough information to answer but keeps searching for more
+- Tool calls are returning empty or error results repeatedly
+- The agent is doing redundant work (searching for things it already found)
+
+A stuck agent will not recover with more time \u2014 it will just burn the budget. Better to force it to answer with what it has.
+
+Respond with ONLY valid JSON (no markdown, no explanation):
+{"extend": true, "minutes": <1-${maxPerReqMin}>, "reason": "your reason here"}
+or
+{"extend": false, "reason": "your reason here"}`;
+            const observerFn = async () => {
+              const modelInstance = this.provider ? this.provider(this.model) : this.model;
+              if (this.debug) {
+                console.log(`[DEBUG] Timeout observer: making LLM call (${activeToolsList.length} active tools, ${elapsedMin} min elapsed)`);
+              }
+              if (this.tracer) {
+                this.tracer.addEvent("negotiated_timeout.observer_invoked", {
+                  elapsed_min: elapsedMin,
+                  active_tools: activeToolsList.map((t) => t.name),
+                  active_tools_detail: activeToolsList.map((t) => ({
+                    name: t.name,
+                    running_for_ms: now - new Date(t.startedAt).getTime(),
+                    args_preview: JSON.stringify(t.args || {}).slice(0, 100)
+                  })),
+                  active_tools_count: activeToolsList.length,
+                  extensions_used: negotiatedTimeoutState.extensionsUsed,
+                  remaining_requests: remainingRequests,
+                  remaining_budget_ms: remainingBudgetMs,
+                  history_length: this.history.length
+                });
+              }
+              const observerResult = await (0, import_ai4.generateText)({
+                model: modelInstance,
+                messages: [{ role: "user", content: observerPrompt }],
+                maxTokens: 500
+              });
+              const responseText = observerResult.text.trim();
+              if (this.tracer) {
+                this.tracer.addEvent("negotiated_timeout.observer_response", {
+                  response_text: responseText,
+                  usage_prompt_tokens: observerResult.usage?.promptTokens,
+                  usage_completion_tokens: observerResult.usage?.completionTokens
+                });
+              }
+              const jsonStr = responseText.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
+              const decision = JSON.parse(jsonStr);
+              if (decision.extend && decision.minutes > 0) {
+                const requestedMs = Math.min(decision.minutes, maxPerReqMin) * 6e4;
+                const grantedMs = Math.min(requestedMs, remainingBudgetMs, negotiatedTimeoutState.maxPerRequestMs);
+                const grantedMin = Math.round(grantedMs / 6e4 * 10) / 10;
+                negotiatedTimeoutState.extensionsUsed++;
+                negotiatedTimeoutState.totalExtraTimeMs += grantedMs;
+                negotiatedTimeoutState.extensionMessage = `\u23F0 Time limit was reached. The timeout observer granted ${grantedMin} more minute(s) (reason: ${decision.reason || "work in progress"}). Extensions remaining: ${negotiatedTimeoutState.maxRequests - negotiatedTimeoutState.extensionsUsed}. Continue your work efficiently.`;
+                negotiatedTimeoutState.softTimeoutId = setTimeout(() => {
+                  runTimeoutObserver();
+                }, grantedMs);
+                if (this.debug) {
+                  console.log(`[DEBUG] Timeout observer: granted ${grantedMin} min (reason: ${decision.reason}). Extensions: ${negotiatedTimeoutState.extensionsUsed}/${negotiatedTimeoutState.maxRequests}`);
+                }
+                if (this.tracer) {
+                  this.tracer.addEvent("negotiated_timeout.observer_extended", {
+                    decision_reason: decision.reason,
+                    requested_minutes: decision.minutes,
+                    granted_ms: grantedMs,
+                    granted_min: grantedMin,
+                    extensions_used: negotiatedTimeoutState.extensionsUsed,
+                    max_requests: negotiatedTimeoutState.maxRequests,
+                    total_extra_time_ms: negotiatedTimeoutState.totalExtraTimeMs,
+                    budget_remaining_ms: remainingBudgetMs - grantedMs,
+                    active_tools: activeToolsList.map((t) => t.name),
+                    active_tools_count: activeToolsList.length
+                  });
+                }
+              } else {
+                if (this.debug) {
+                  console.log(`[DEBUG] Timeout observer: declined extension (reason: ${decision.reason}). Initiating graceful stop.`);
+                }
+                if (this.tracer) {
+                  this.tracer.addEvent("negotiated_timeout.observer_declined", {
+                    decision_reason: decision.reason,
+                    extensions_used: negotiatedTimeoutState.extensionsUsed,
+                    total_extra_time_ms: negotiatedTimeoutState.totalExtraTimeMs,
+                    elapsed_min: elapsedMin,
+                    active_tools: activeToolsList.map((t) => t.name)
+                  });
+                }
+                await this._initiateGracefulStop(gracefulTimeoutState, `observer declined: ${decision.reason}`);
+              }
+            };
+            try {
+              if (this.tracer) {
+                await this.tracer.withSpan("negotiated_timeout.observer", observerFn, {
+                  "timeout.elapsed_min": elapsedMin,
+                  "timeout.extensions_used": negotiatedTimeoutState.extensionsUsed,
+                  "timeout.active_tools_count": activeToolsList.length,
+                  "timeout.remaining_budget_ms": remainingBudgetMs
+                });
+              } else {
+                await observerFn();
+              }
+            } catch (err) {
+              if (this.debug) {
+                console.log(`[DEBUG] Timeout observer: LLM call failed (${err.message}). Initiating graceful stop.`);
+              }
+              if (this.tracer) {
+                this.tracer.addEvent("negotiated_timeout.observer_error", {
+                  error_message: err.message,
+                  error_name: err.name,
+                  extensions_used: negotiatedTimeoutState.extensionsUsed,
+                  elapsed_min: elapsedMin
+                });
+              }
+              await this._initiateGracefulStop(gracefulTimeoutState, `observer error: ${err.message}`);
+            } finally {
+              negotiatedTimeoutState.observerRunning = false;
+            }
+          };
+          negotiatedTimeoutState.runObserver = runTimeoutObserver;
           let compactionAttempted = false;
           while (true) {
             try {
@@ -99319,6 +99718,15 @@ You are working with a workspace. Available paths: ${workspaceDesc}
                 messages: messagesForAI,
                 tools: tools2,
                 stopWhen: ({ steps }) => {
+                  if (gracefulTimeoutState.triggered) {
+                    if (gracefulTimeoutState.bonusStepsUsed >= gracefulTimeoutState.bonusStepsMax) {
+                      if (this.debug) {
+                        console.log(`[DEBUG] stopWhen: graceful timeout bonus steps exhausted (${gracefulTimeoutState.bonusStepsUsed}/${gracefulTimeoutState.bonusStepsMax}), forcing stop`);
+                      }
+                      return true;
+                    }
+                    return false;
+                  }
                   if (steps.length >= maxIterations) return true;
                   const lastStep = steps[steps.length - 1];
                   const modelWantsToStop = lastStep?.finishReason === "stop" && (!lastStep?.toolCalls || lastStep.toolCalls.length === 0);
@@ -99362,9 +99770,45 @@ You are working with a workspace. Available paths: ${workspaceDesc}
                   return false;
                 },
                 prepareStep: ({ steps, stepNumber }) => {
+                  if (negotiatedTimeoutState.extensionMessage && !gracefulTimeoutState.triggered) {
+                    const msg = negotiatedTimeoutState.extensionMessage;
+                    negotiatedTimeoutState.extensionMessage = null;
+                    if (this.debug) {
+                      console.log(`[DEBUG] prepareStep: delivering timeout observer extension message`);
+                    }
+                    return { userMessage: msg };
+                  }
+                  if (gracefulTimeoutState.triggered) {
+                    gracefulTimeoutState.bonusStepsUsed++;
+                    const remaining = gracefulTimeoutState.bonusStepsMax - gracefulTimeoutState.bonusStepsUsed;
+                    if (gracefulTimeoutState.bonusStepsUsed === 1) {
+                      if (this.debug) {
+                        console.log(`[DEBUG] prepareStep: graceful timeout wind-down step 1/${gracefulTimeoutState.bonusStepsMax}`);
+                      }
+                      if (this.tracer) {
+                        this.tracer.addEvent("graceful_timeout.wind_down_started", {
+                          bonus_steps_max: gracefulTimeoutState.bonusStepsMax,
+                          current_iteration: currentIteration,
+                          max_iterations: maxIterations
+                        });
+                      }
+                      return {
+                        toolChoice: "none",
+                        userMessage: `\u26A0\uFE0F TIME LIMIT REACHED. You are running out of time. You have ${remaining} step(s) remaining. Provide your BEST answer NOW using the information you have already gathered. Do NOT call any more tools. Summarize your findings and respond completely. If something was not completed, honestly state what was not done and provide any partial results or recommendations you can offer.`
+                      };
+                    }
+                    if (this.debug) {
+                      console.log(`[DEBUG] prepareStep: graceful timeout wind-down step ${gracefulTimeoutState.bonusStepsUsed}/${gracefulTimeoutState.bonusStepsMax} (${remaining} remaining)`);
+                    }
+                    return { toolChoice: "none" };
+                  }
                   if (stepNumber === maxIterations - 1) {
+                    const searchesTried = _toolCallLog.filter((tc) => tc.name === "search").map((tc) => `"${tc.args.query || ""}"${tc.args.exact ? " (exact)" : ""}`).filter((v, i, a) => a.indexOf(v) === i);
+                    const searchSummary = searchesTried.length > 0 ? `
+Searches attempted: ${searchesTried.join(", ")}` : "";
                     return {
-                      toolChoice: "none"
+                      toolChoice: "none",
+                      userMessage: `\u26A0\uFE0F LAST ITERATION \u2014 you are out of tool calls. Provide your BEST answer NOW with the information gathered so far. If you could not find what was requested, explain exactly what you searched for and why it did not work, so the caller can try a different approach.${searchSummary}`
                     };
                   }
                   if (steps.length >= 2) {
@@ -99443,6 +99887,11 @@ Double-check your response based on the criteria above. If everything looks good
                   const { toolResults, toolCalls, text, reasoningText, finishReason, usage } = stepResult;
                   currentIteration++;
                   toolContext.currentIteration = currentIteration;
+                  if (toolCalls?.length > 0) {
+                    for (const tc of toolCalls) {
+                      _toolCallLog.push({ name: tc.toolName, args: tc.args || {} });
+                    }
+                  }
                   if (this.tracer) {
                     const stepEvent = {
                       "iteration": currentIteration,
@@ -99465,6 +99914,12 @@ Double-check your response based on the criteria above. If everything looks good
                       }));
                     }
                     this.tracer.addEvent("iteration.step", stepEvent);
+                    if (gracefulTimeoutState.triggered) {
+                      this.tracer.addEvent("graceful_timeout.wind_down_step", {
+                        bonus_step: gracefulTimeoutState.bonusStepsUsed,
+                        bonus_max: gracefulTimeoutState.bonusStepsMax
+                      });
+                    }
                   }
                   if (usage) {
                     this.tokenCounter.recordUsage(usage);
@@ -99510,22 +99965,59 @@ Double-check your response based on the criteria above. If everything looks good
               }
               const executeAIRequest = async () => {
                 const result = await this.streamTextWithRetryAndFallback(streamOptions);
-                const steps = await result.steps;
-                let finalText;
-                if (steps && steps.length > 1) {
-                  const lastStepText = steps[steps.length - 1].text;
-                  finalText = lastStepText || await result.text;
-                } else {
-                  finalText = await result.text;
+                let gracefulTimeoutId = null;
+                let hardAbortTimeoutId = null;
+                if (this.timeoutBehavior === "graceful" && gracefulTimeoutState && this.maxOperationTimeout > 0) {
+                  gracefulTimeoutId = setTimeout(() => {
+                    gracefulTimeoutState.triggered = true;
+                    if (this.debug) {
+                      console.log(`[DEBUG] Soft timeout after ${this.maxOperationTimeout}ms \u2014 entering wind-down mode (${gracefulTimeoutState.bonusStepsMax} bonus steps)`);
+                    }
+                    hardAbortTimeoutId = setTimeout(() => {
+                      if (this._abortController) {
+                        this._abortController.abort();
+                      }
+                      if (this.debug) {
+                        console.log(`[DEBUG] Hard abort \u2014 wind-down safety net expired after 60s`);
+                      }
+                    }, 6e4);
+                  }, this.maxOperationTimeout);
                 }
-                if (this.debug) {
-                  console.log(`[DEBUG] streamText completed: ${steps?.length || 0} steps, finalText=${finalText?.length || 0} chars`);
+                if (this.timeoutBehavior === "negotiated" && this.maxOperationTimeout > 0) {
+                  negotiatedTimeoutState.softTimeoutId = setTimeout(() => {
+                    if (this.debug) {
+                      console.log(`[DEBUG] Soft timeout after ${this.maxOperationTimeout}ms \u2014 invoking timeout observer`);
+                    }
+                    runTimeoutObserver();
+                  }, this.maxOperationTimeout);
                 }
-                const usage = await result.usage;
-                if (usage) {
-                  this.tokenCounter.recordUsage(usage, result.experimental_providerMetadata);
+                try {
+                  const steps = await result.steps;
+                  let finalText;
+                  if (steps && steps.length > 1) {
+                    const lastStepText = steps[steps.length - 1].text;
+                    finalText = lastStepText || await result.text;
+                  } else {
+                    finalText = await result.text;
+                  }
+                  if (this.debug) {
+                    console.log(`[DEBUG] streamText completed: ${steps?.length || 0} steps, finalText=${finalText?.length || 0} chars`);
+                  }
+                  const usage = await result.usage;
+                  if (usage) {
+                    this.tokenCounter.recordUsage(usage, result.experimental_providerMetadata);
+                  }
+                  return { finalText, result };
+                } finally {
+                  if (gracefulTimeoutId) clearTimeout(gracefulTimeoutId);
+                  if (hardAbortTimeoutId) clearTimeout(hardAbortTimeoutId);
+                  if (negotiatedTimeoutState.softTimeoutId) clearTimeout(negotiatedTimeoutState.softTimeoutId);
+                  if (this._gracefulStopHardAbortId) {
+                    clearTimeout(this._gracefulStopHardAbortId);
+                    this._gracefulStopHardAbortId = null;
+                  }
+                  this.events.removeListener("toolCall", onToolCall);
                 }
-                return { finalText, result };
               };
               let aiResult;
               if (this.tracer) {
@@ -99562,13 +100054,57 @@ Double-check your response based on the criteria above. If everything looks good
               } else if (aiResult.finalText) {
                 finalResult = aiResult.finalText;
               }
+              if (gracefulTimeoutState.triggered) {
+                const timeoutNotice = "**Note: This response was generated under a time constraint. The research may be incomplete, and some planned searches or analysis steps were not completed.**\n\n";
+                if (!finalResult || finalResult === DEFAULT_MAX_ITER_MSG || finalResult.startsWith("I was unable to complete your request after")) {
+                  try {
+                    const allText = await aiResult.result.text;
+                    if (allText && allText.trim()) {
+                      finalResult = timeoutNotice + allText;
+                      if (this.debug) {
+                        console.log(`[DEBUG] Graceful timeout: using concatenated step text (${allText.length} chars)`);
+                      }
+                    } else {
+                      const steps = await aiResult.result.steps;
+                      const toolSummaries = [];
+                      for (const step of steps || []) {
+                        if (step.toolResults?.length > 0) {
+                          for (const tr of step.toolResults) {
+                            const resultText = typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result);
+                            if (resultText && resultText.length > 0 && resultText.length < 5e3) {
+                              toolSummaries.push(resultText.substring(0, 2e3));
+                            }
+                          }
+                        }
+                      }
+                      if (toolSummaries.length > 0) {
+                        finalResult = `${timeoutNotice}The operation timed out before a complete answer could be generated. Here is the partial information gathered:
+
+${toolSummaries.join("\n\n---\n\n")}`;
+                        if (this.debug) {
+                          console.log(`[DEBUG] Graceful timeout: built fallback from ${toolSummaries.length} tool results`);
+                        }
+                      } else {
+                        finalResult = "The operation timed out before enough information could be gathered to provide an answer. Please try again with a simpler query or increase the timeout.";
+                      }
+                    }
+                  } catch (e) {
+                    if (this.debug) {
+                      console.log(`[DEBUG] Graceful timeout fallback error: ${e.message}`);
+                    }
+                    finalResult = "The operation timed out before enough information could be gathered to provide an answer. Please try again with a simpler query or increase the timeout.";
+                  }
+                } else {
+                  finalResult = timeoutNotice + finalResult;
+                }
+              }
               const resultMessages = await aiResult.result.response?.messages;
               if (resultMessages) {
                 for (const msg of resultMessages) {
                   currentMessages.push(msg);
                 }
               }
-              if (this.completionPrompt && !options._completionPromptProcessed && !completionPromptInjected && finalResult) {
+              if (this.completionPrompt && !options._completionPromptProcessed && !completionPromptInjected && !abortSummaryTaken && finalResult) {
                 completionPromptInjected = true;
                 preCompletionResult = finalResult;
                 if (this.debug) {
@@ -99640,6 +100176,118 @@ Double-check your response based on the criteria above. If everything looks good
               }
               break;
             } catch (error40) {
+              if (gracefulTimeoutState.triggered && error40?.name === "AbortError") {
+                if (this.debug) {
+                  console.log(`[DEBUG] Negotiated timeout: abort caught \u2014 making summary LLM call with conversation context`);
+                }
+                if (this.tracer) {
+                  this.tracer.addEvent("negotiated_timeout.abort_summary_started", {
+                    conversation_messages: currentMessages.length,
+                    has_schema: !!options.schema,
+                    has_tasks: !!(this.enableTasks && this.taskManager)
+                  });
+                }
+                try {
+                  let taskContext = "";
+                  if (this.enableTasks && this.taskManager) {
+                    const taskSummary = this.taskManager.getTaskSummary?.();
+                    if (taskSummary) {
+                      taskContext = `
+
+## Task Status
+${taskSummary}
+
+Acknowledge which tasks were completed and which were not.`;
+                    }
+                  }
+                  let schemaContext = "";
+                  if (options.schema) {
+                    try {
+                      const parsedSchema = typeof options.schema === "string" ? JSON.parse(options.schema) : options.schema;
+                      schemaContext = `
+
+IMPORTANT: Your response MUST be valid JSON matching this schema:
+${JSON.stringify(parsedSchema, null, 2)}
+
+Respond with ONLY valid JSON \u2014 no markdown, no explanation, no text outside the JSON object. Include all findings and partial results within the JSON structure. If fields cannot be fully populated due to the interruption, use partial data or null values as appropriate.`;
+                    } catch {
+                    }
+                  }
+                  const summaryPrompt = `Your operation was interrupted by a timeout observer because the time limit was reached. Some of your tool calls were cancelled mid-execution.
+
+Please provide a DETAILED summary of:
+1. What you were asked to do (the original task)
+2. What you accomplished \u2014 include ALL findings, code snippets, data, and conclusions you gathered
+3. What was still in progress or not yet started
+4. Any partial results or recommendations you can offer based on what you found so far${taskContext}${schemaContext}
+
+Be thorough \u2014 this is the user's only response. Include all useful information you collected.`;
+                  const summaryMessages = [
+                    ...currentMessages,
+                    { role: "user", content: summaryPrompt }
+                  ];
+                  const modelInstance = this.provider ? this.provider(this.model) : this.model;
+                  const summaryFn = async () => {
+                    const summaryResult = await (0, import_ai4.generateText)({
+                      model: modelInstance,
+                      messages: this.prepareMessagesWithImages(summaryMessages),
+                      maxTokens: 4e3
+                    });
+                    if (this.tracer) {
+                      this.tracer.addEvent("negotiated_timeout.abort_summary_completed", {
+                        summary_length: summaryResult.text?.length || 0,
+                        usage_prompt_tokens: summaryResult.usage?.promptTokens,
+                        usage_completion_tokens: summaryResult.usage?.completionTokens
+                      });
+                    }
+                    if (summaryResult.usage) {
+                      this.tokenCounter.recordUsage(summaryResult.usage);
+                    }
+                    return summaryResult.text;
+                  };
+                  let summaryText;
+                  if (this.tracer) {
+                    summaryText = await this.tracer.withSpan("negotiated_timeout.abort_summary", summaryFn, {
+                      "summary.conversation_messages": currentMessages.length
+                    });
+                  } else {
+                    summaryText = await summaryFn();
+                  }
+                  if (options.schema) {
+                    finalResult = summaryText || "{}";
+                  } else {
+                    const timeoutNotice = "**Note: This response was generated under a time constraint. The timeout observer interrupted the operation because the time budget was exhausted.**\n\n";
+                    finalResult = timeoutNotice + (summaryText || "The operation was interrupted before a response could be generated.");
+                  }
+                  if (options.onStream && finalResult) {
+                    options.onStream(finalResult);
+                  }
+                  if (this.debug) {
+                    console.log(`[DEBUG] Negotiated timeout: summary produced ${summaryText?.length || 0} chars`);
+                  }
+                } catch (summaryErr) {
+                  if (this.debug) {
+                    console.log(`[DEBUG] Negotiated timeout: summary call failed (${summaryErr.message}), falling back to partial text`);
+                  }
+                  if (this.tracer) {
+                    this.tracer.addEvent("negotiated_timeout.abort_summary_error", {
+                      error_message: summaryErr.message
+                    });
+                  }
+                  const partialTexts = currentMessages.filter((m) => m.role === "assistant" && typeof m.content === "string" && m.content.trim()).map((m) => m.content);
+                  if (options.schema) {
+                    finalResult = partialTexts.length > 0 ? partialTexts[partialTexts.length - 1] : "{}";
+                  } else {
+                    const timeoutNotice = "**Note: This response was generated under a time constraint. The operation was interrupted and some work was not completed.**\n\n";
+                    finalResult = partialTexts.length > 0 ? timeoutNotice + partialTexts[partialTexts.length - 1] : timeoutNotice + "The operation was interrupted before enough information could be gathered. Please try again with a simpler query or increase the timeout.";
+                  }
+                  if (options.onStream && finalResult) {
+                    options.onStream(finalResult);
+                  }
+                }
+                abortSummaryTaken = true;
+                break;
+              }
               if (!compactionAttempted && handleContextLimitError) {
                 const compactionResult = handleContextLimitError(error40, currentMessages, {
                   keepLastSegment: true,
@@ -99674,6 +100322,36 @@ Double-check your response based on the criteria above. If everything looks good
           }
           if (currentIteration >= maxIterations) {
             console.warn(`[WARN] Max tool iterations (${maxIterations}) reached for session ${this.sessionId}.`);
+            if (!finalResult || finalResult === DEFAULT_MAX_ITER_MSG) {
+              try {
+                const searchQueries = [];
+                const toolCounts = {};
+                for (const tc of _toolCallLog) {
+                  toolCounts[tc.name] = (toolCounts[tc.name] || 0) + 1;
+                  if (tc.name === "search") {
+                    const q = tc.args.query || "";
+                    const exact = tc.args.exact ? " (exact)" : "";
+                    searchQueries.push(`"${q}"${exact}`);
+                  }
+                }
+                const toolBreakdown = Object.entries(toolCounts).map(([name15, count]) => `${name15}: ${count}x`).join(", ");
+                const uniqueSearches = [...new Set(searchQueries)];
+                let summary = `I was unable to complete your request after ${currentIteration} tool iterations.
+
+`;
+                summary += `Tool calls made: ${toolBreakdown || "none"}
+`;
+                if (uniqueSearches.length > 0) {
+                  summary += `Search queries tried: ${uniqueSearches.join(", ")}
+`;
+                }
+                summary += `
+The search approach may be fundamentally wrong for this query. Consider: using exact=true for literal string matching, using bash/grep for pattern-based file searches, or trying a completely different strategy instead of repeating similar searches.`;
+                finalResult = summary;
+              } catch {
+                finalResult = DEFAULT_MAX_ITER_MSG;
+              }
+            }
           }
           this.history = currentMessages.map((msg) => ({ ...msg }));
           if (this.history.length > MAX_HISTORY_MESSAGES) {
@@ -100208,6 +100886,134 @@ Double-check your response based on the criteria above. If everything looks good
           console.log(`[DEBUG] Agent cancelled for session ${this.sessionId}`);
         }
       }
+      /**
+       * Trigger graceful wind-down from outside (e.g., parent agent).
+       * Unlike cancel(), this does NOT abort — it sets the graceful timeout flag
+       * so the agent finishes its current step and then winds down naturally.
+       */
+      triggerGracefulWindDown() {
+        if (this._gracefulTimeoutState && !this._gracefulTimeoutState.triggered) {
+          this._gracefulTimeoutState.triggered = true;
+          if (this.debug) {
+            console.log(`[DEBUG] Graceful wind-down triggered externally for session ${this.sessionId}`);
+          }
+          if (this.tracer) {
+            this.tracer.addEvent("graceful_stop.external_trigger", {
+              "session.id": this.sessionId
+            });
+          }
+        } else if (this.debug) {
+          console.log(`[DEBUG] Graceful wind-down already active for session ${this.sessionId}, skipping`);
+        }
+      }
+      /**
+       * Initiate two-phase graceful stop: signal subagents and MCP servers to wind down,
+       * then hard-abort after a deadline if they haven't finished.
+       * @param {Object} gracefulTimeoutState - The graceful timeout state object from run()
+       * @param {string} reason - Why the graceful stop was initiated
+       */
+      async _initiateGracefulStop(gracefulTimeoutState, reason) {
+        if (gracefulTimeoutState.triggered) return;
+        if (this.debug) {
+          console.log(`[DEBUG] Initiating graceful stop: ${reason} (subagents: ${this._activeSubagents.size}, hasMcpBridge: ${!!this.mcpBridge}, deadline: ${this.gracefulStopDeadline}ms)`);
+        }
+        gracefulTimeoutState.triggered = true;
+        if (this.tracer) {
+          this.tracer.addEvent("graceful_stop.initiated", {
+            "session.id": this.sessionId,
+            "graceful_stop.reason": reason,
+            "graceful_stop.active_subagents": this._activeSubagents.size,
+            "graceful_stop.has_mcp_bridge": !!this.mcpBridge,
+            "graceful_stop.deadline_ms": this.gracefulStopDeadline
+          });
+        }
+        let subagentsSignalled = 0;
+        let subagentErrors = 0;
+        for (const [sid, subagent] of this._activeSubagents) {
+          try {
+            subagent.triggerGracefulWindDown();
+            subagentsSignalled++;
+            if (this.debug) {
+              console.log(`[DEBUG] Triggered graceful wind-down on subagent ${sid}`);
+            }
+          } catch (e) {
+            subagentErrors++;
+            if (this.debug) {
+              console.log(`[DEBUG] Failed to trigger wind-down on subagent ${sid}: ${e.message}`);
+            }
+          }
+        }
+        let mcpResults = [];
+        if (this.mcpBridge) {
+          try {
+            mcpResults = await this.mcpBridge.callGracefulStopAll();
+            if (this.debug && mcpResults.length > 0) {
+              console.log(`[DEBUG] MCP graceful_stop results: ${JSON.stringify(mcpResults)}`);
+            }
+          } catch (e) {
+            if (this.debug) {
+              console.log(`[DEBUG] MCP graceful_stop failed: ${e.message}`);
+            }
+          }
+        }
+        if (this.tracer) {
+          this.tracer.addEvent("graceful_stop.signals_sent", {
+            "session.id": this.sessionId,
+            "graceful_stop.subagents_signalled": subagentsSignalled,
+            "graceful_stop.subagent_errors": subagentErrors,
+            "graceful_stop.mcp_servers_called": mcpResults.filter((r) => r.success).length,
+            "graceful_stop.mcp_servers_failed": mcpResults.filter((r) => !r.success).length,
+            "graceful_stop.mcp_servers_total": mcpResults.length
+          });
+        }
+        this._gracefulStopHardAbortId = setTimeout(() => {
+          if (this.debug) {
+            console.log(`[DEBUG] Graceful stop deadline (${this.gracefulStopDeadline}ms) expired \u2014 hard aborting`);
+          }
+          if (this.tracer) {
+            this.tracer.addEvent("graceful_stop.deadline_expired", {
+              "session.id": this.sessionId,
+              "graceful_stop.deadline_ms": this.gracefulStopDeadline
+            });
+          }
+          if (this._abortController) this._abortController.abort();
+        }, this.gracefulStopDeadline);
+      }
+      /**
+       * Register an active subagent for graceful stop coordination.
+       * @param {string} sessionId
+       * @param {ProbeAgent} subagent
+       */
+      _registerSubagent(sessionId, subagent) {
+        this._activeSubagents.set(sessionId, subagent);
+        if (this.debug) {
+          console.log(`[DEBUG] Registered subagent ${sessionId} (active: ${this._activeSubagents.size})`);
+        }
+        if (this.tracer) {
+          this.tracer.addEvent("subagent.registered", {
+            "session.id": this.sessionId,
+            "subagent.session_id": sessionId,
+            "subagent.active_count": this._activeSubagents.size
+          });
+        }
+      }
+      /**
+       * Unregister a completed subagent.
+       * @param {string} sessionId
+       */
+      _unregisterSubagent(sessionId) {
+        this._activeSubagents.delete(sessionId);
+        if (this.debug) {
+          console.log(`[DEBUG] Unregistered subagent ${sessionId} (active: ${this._activeSubagents.size})`);
+        }
+        if (this.tracer) {
+          this.tracer.addEvent("subagent.unregistered", {
+            "session.id": this.sessionId,
+            "subagent.session_id": sessionId,
+            "subagent.active_count": this._activeSubagents.size
+          });
+        }
+      }
       /**
        * Get the abort signal for this agent.
        * Delegations and subagents should check this signal.
@@ -100250,8 +101056,15 @@ async function delegate({
   // Optional per-instance manager, falls back to default singleton
   concurrencyLimiter = null,
   // Optional global AI concurrency limiter
-  parentAbortSignal = null
+  parentAbortSignal = null,
   // Optional AbortSignal from parent to cancel this delegation
+  // Timeout settings inherited from parent agent
+  timeoutBehavior = void 0,
+  requestTimeout = void 0,
+  gracefulTimeoutBonusSteps = void 0,
+  // Subagent lifecycle callbacks for graceful stop coordination
+  onSubagentCreated = null,
+  onSubagentCompleted = null
 }) {
   if (!task || typeof task !== "string") {
     throw new Error("Task parameter is required and must be a string");
@@ -100334,12 +101147,38 @@ async function delegate({
       // Inherit from parent
       mcpConfigPath,
       // Inherit from parent
-      concurrencyLimiter
+      concurrencyLimiter,
       // Inherit global AI concurrency limiter
+      // Inherit timeout behavior from parent — subagent gets its own graceful wind-down
+      // so it can produce partial results instead of being hard-killed by the external timer.
+      // The external delegate timeout (capped to parent's remaining budget) is the hard limit;
+      // maxOperationTimeout on the subagent is set slightly shorter so its own wind-down
+      // fires before the external kill.
+      maxOperationTimeout: Math.max(1e4, timeout * 1e3 - 15e3),
+      // 15s before external kill
+      timeoutBehavior: timeoutBehavior || "graceful",
+      requestTimeout,
+      gracefulTimeoutBonusSteps: gracefulTimeoutBonusSteps ?? 2
+      // fewer steps for subagents
     });
+    if (onSubagentCreated) {
+      onSubagentCreated(sessionId, subagent);
+    }
     if (debug) {
       console.error(`[DELEGATE] Created subagent with session ${sessionId}`);
       console.error(`[DELEGATE] Subagent config: promptType=${promptType}, enableDelegate=false, maxIterations=${remainingIterations}`);
+      console.error(`[DELEGATE] Timeout inheritance: externalTimeout=${timeout}s, maxOperationTimeout=${Math.max(1e4, timeout * 1e3 - 15e3)}ms, behavior=${timeoutBehavior || "graceful"}, bonusSteps=${gracefulTimeoutBonusSteps ?? 2}`);
+    }
+    if (tracer) {
+      tracer.addEvent("delegation.subagent_created", {
+        "delegation.session_id": sessionId,
+        "delegation.parent_session_id": parentSessionId,
+        "delegation.external_timeout_s": timeout,
+        "delegation.internal_timeout_ms": Math.max(1e4, timeout * 1e3 - 15e3),
+        "delegation.timeout_behavior": timeoutBehavior || "graceful",
+        "delegation.bonus_steps": gracefulTimeoutBonusSteps ?? 2,
+        "delegation.max_iterations": remainingIterations
+      });
     }
     const timeoutPromise = new Promise((_, reject2) => {
       timeoutId = setTimeout(() => {
@@ -100348,6 +101187,7 @@ async function delegate({
       }, timeout * 1e3);
     });
     let parentAbortHandler;
+    let parentAbortHardCancelId = null;
     const parentAbortPromise = new Promise((_, reject2) => {
       if (parentAbortSignal) {
         if (parentAbortSignal.aborted) {
@@ -100356,8 +101196,31 @@ async function delegate({
           return;
         }
         parentAbortHandler = () => {
-          subagent.cancel();
-          reject2(new Error("Delegation cancelled: parent operation was aborted"));
+          subagent.triggerGracefulWindDown();
+          if (debug) {
+            console.error(`[DELEGATE] Parent abort signal received \u2014 triggered graceful wind-down on subagent ${sessionId}`);
+          }
+          if (tracer) {
+            tracer.addEvent("delegation.parent_abort_phase1", {
+              "delegation.session_id": sessionId,
+              "delegation.parent_session_id": parentSessionId,
+              "delegation.action": "graceful_wind_down"
+            });
+          }
+          parentAbortHardCancelId = setTimeout(() => {
+            if (debug) {
+              console.error(`[DELEGATE] Graceful wind-down deadline expired \u2014 hard cancelling subagent ${sessionId}`);
+            }
+            if (tracer) {
+              tracer.addEvent("delegation.parent_abort_phase2", {
+                "delegation.session_id": sessionId,
+                "delegation.parent_session_id": parentSessionId,
+                "delegation.action": "hard_cancel"
+              });
+            }
+            subagent.cancel();
+            reject2(new Error("Delegation cancelled: parent operation was aborted (graceful wind-down deadline expired)"));
+          }, 3e4);
         };
         parentAbortSignal.addEventListener("abort", parentAbortHandler, { once: true });
       }
@@ -100373,6 +101236,13 @@ async function delegate({
       if (parentAbortHandler && parentAbortSignal) {
         parentAbortSignal.removeEventListener("abort", parentAbortHandler);
       }
+      if (parentAbortHardCancelId) {
+        clearTimeout(parentAbortHardCancelId);
+        parentAbortHardCancelId = null;
+      }
+      if (onSubagentCompleted) {
+        onSubagentCompleted(sessionId);
+      }
     }
     if (timeoutId !== null) {
       clearTimeout(timeoutId);
@@ -101397,6 +102267,10 @@ function buildSearchDelegateTask({ searchQuery, searchPath, exact, language, all
     "- Use exact=true when searching for a KNOWN symbol name (function, type, variable, struct).",
     "- exact=true matches the literal string only \u2014 no stemming, no splitting.",
     '- This is ideal for precise lookups: exact=true "ForwardMessage", exact=true "SessionLimiter", exact=true "ThrottleRetryLimit".',
+    "- IMPORTANT: Use exact=true when searching for strings containing punctuation, quotes, or empty values.",
+    "  Default BM25 search strips punctuation and treats quoted empty strings as noise.",
+    `  Example: searching for 'description: ""' with exact=false will NOT find empty description fields \u2014 it just matches "description".`,
+    `  Use exact=true for literal patterns like 'description: ""', 'value: \\'\\'', or any YAML/config field with specific punctuation.`,
     "- Do NOT use exact=true for exploratory/conceptual queries \u2014 use the default for those.",
     "",
     "Combining searches with OR:",
@@ -101456,7 +102330,13 @@ function buildSearchDelegateTask({ searchQuery, searchPath, exact, language, all
     "WHEN TO STOP:",
     "- After you have explored the main concept AND related subsystems.",
     "- Once you have 5-15 targets covering different aspects of the query.",
-    '- If you get a "DUPLICATE SEARCH BLOCKED" message, move on.',
+    '- If you get a "DUPLICATE SEARCH BLOCKED" message, do NOT rephrase the same query \u2014 try a FUNDAMENTALLY different approach:',
+    "  * Switch between exact=true and exact=false",
+    "  * Search for a broader term and filter results manually",
+    "  * Use listFiles to browse the directory structure directly",
+    "  * Look for related/surrounding patterns instead of the exact string",
+    "- If 2-3 genuinely different search approaches fail, STOP and report what you tried and why it failed.",
+    "  Do NOT keep trying variations of the same failing concept.",
     "",
     "Strategy:",
     "1. Analyze the query \u2014 identify key concepts, then brainstorm SYNONYMS and alternative terms for each.",
@@ -101528,8 +102408,8 @@ var init_vercel = __esm({
         }
         return result;
       };
-      const previousSearches = /* @__PURE__ */ new Set();
-      let consecutiveDupBlocks = 0;
+      const previousSearches = /* @__PURE__ */ new Map();
+      const dupBlockCounts = /* @__PURE__ */ new Map();
       const paginationCounts = /* @__PURE__ */ new Map();
       const MAX_PAGES_PER_QUERY = 3;
       return (0, import_ai5.tool)({
@@ -101580,20 +102460,25 @@ var init_vercel = __esm({
             return await search(searchOptions);
           };
           if (!searchDelegate) {
-            const searchKey = `${searchQuery}::${exact || false}`;
+            const searchKey = `${searchPath}::${searchQuery}::${exact || false}`;
             if (!nextPage) {
               if (previousSearches.has(searchKey)) {
-                consecutiveDupBlocks++;
+                const blockCount = (dupBlockCounts.get(searchKey) || 0) + 1;
+                dupBlockCounts.set(searchKey, blockCount);
                 if (debug) {
-                  console.error(`[DEDUP] Blocked duplicate search (${consecutiveDupBlocks}x): "${searchQuery}" (path: "${searchPath}")`);
+                  console.error(`[DEDUP] Blocked duplicate search (${blockCount}x): "${searchQuery}" (path: "${searchPath}")`);
+                }
+                if (blockCount >= 3) {
+                  return "STOP. You have been blocked " + blockCount + " times for repeating the same search. You MUST provide your final answer NOW with whatever information you have. Do NOT call any more tools.";
                 }
-                if (consecutiveDupBlocks >= 3) {
-                  return "STOP. You have been blocked " + consecutiveDupBlocks + " times for repeating searches. You MUST output your final JSON answer NOW with whatever targets you have found. Do NOT call any more tools.";
+                const prev = previousSearches.get(searchKey);
+                if (prev.hadResults) {
+                  return `DUPLICATE SEARCH BLOCKED (${blockCount}x). You already searched for "${searchQuery}" in this path and found results. Do NOT repeat. Use extract to examine the files you already found, try a COMPLETELY different keyword, or provide your final answer.`;
                 }
-                return "DUPLICATE SEARCH BLOCKED (" + consecutiveDupBlocks + "x). You already searched for this. Do NOT repeat \u2014 probe searches recursively across all paths. Either: (1) use extract on results you already found, (2) try a COMPLETELY different keyword, or (3) output your final answer NOW.";
+                const exactHint = exact ? "You used exact=true. Try a broader search with exact=false, or use listFiles to browse the directory structure." : `Try exact=true if you need literal/punctuation matching (e.g. 'description: ""'), or use listFiles to explore directories, or search for a broader/related term and filter manually.`;
+                return `DUPLICATE SEARCH BLOCKED (${blockCount}x). You already searched for "${searchQuery}" in this path and got NO results. This term does not appear in the codebase. Do NOT repeat or rephrase \u2014 try a FUNDAMENTALLY different approach: ${exactHint} If multiple approaches have failed, provide your final answer with what you know.`;
               }
-              previousSearches.add(searchKey);
-              consecutiveDupBlocks = 0;
+              previousSearches.set(searchKey, { hadResults: false });
               paginationCounts.set(searchKey, 0);
             } else {
               const pageCount = (paginationCounts.get(searchKey) || 0) + 1;
@@ -101607,6 +102492,14 @@ var init_vercel = __esm({
             }
             try {
               const result = maybeAnnotate(await runRawSearch());
+              if (typeof result === "string" && result.includes("No results found")) {
+                if (/^[A-Z]+-\d+$/.test(searchQuery.trim()) || /^[A-Z]+-\d+$/.test(searchQuery.replace(/"/g, "").trim())) {
+                  return result + "\n\n\u26A0\uFE0F Your query looks like a ticket/issue ID (e.g., JIRA-1234). Ticket IDs are rarely present in source code. Search for the technical concepts described in the ticket instead (e.g., function names, error messages, variable names).";
+                }
+              } else if (typeof result === "string") {
+                const entry = previousSearches.get(searchKey);
+                if (entry) entry.hadResults = true;
+              }
               if (options.fileTracker && typeof result === "string") {
                 options.fileTracker.trackFilesFromOutput(result, effectiveSearchCwd).catch(() => {
                 });
@@ -101889,7 +102782,31 @@ var init_vercel = __esm({
       });
     };
     delegateTool = (options = {}) => {
-      const { debug = false, timeout = 300, cwd, allowedFolders, workspaceRoot, enableBash = false, bashConfig, architectureFileName, enableMcp = false, mcpConfig = null, mcpConfigPath = null, delegationManager = null } = options;
+      const {
+        debug = false,
+        timeout = 300,
+        cwd,
+        allowedFolders,
+        workspaceRoot,
+        enableBash = false,
+        bashConfig,
+        architectureFileName,
+        enableMcp = false,
+        mcpConfig = null,
+        mcpConfigPath = null,
+        delegationManager = null,
+        // Timeout settings inherited from parent agent
+        timeoutBehavior,
+        maxOperationTimeout,
+        requestTimeout,
+        gracefulTimeoutBonusSteps,
+        negotiatedTimeoutBudget,
+        negotiatedTimeoutMaxRequests,
+        negotiatedTimeoutMaxPerRequest,
+        parentOperationStartTime,
+        onSubagentCreated,
+        onSubagentCompleted
+      } = options;
       return (0, import_ai5.tool)({
         name: "delegate",
         description: delegateDescription,
@@ -101933,9 +102850,30 @@ var init_vercel = __esm({
               console.error(`Using workspace root: ${effectivePath} (cwd was: ${cwd || "not set"})`);
             }
           }
+          let effectiveTimeout = timeout;
+          if (parentOperationStartTime && maxOperationTimeout) {
+            const elapsed = Date.now() - parentOperationStartTime;
+            const remaining = maxOperationTimeout - elapsed;
+            const budgetCap = Math.max(30, Math.floor(remaining * 0.9 / 1e3));
+            if (budgetCap < effectiveTimeout) {
+              effectiveTimeout = budgetCap;
+              if (debug) {
+                console.error(`[DELEGATE] Capping timeout from ${timeout}s to ${effectiveTimeout}s (remaining parent budget: ${Math.floor(remaining / 1e3)}s)`);
+              }
+              if (tracer) {
+                tracer.addEvent("delegation.budget_capped", {
+                  "delegation.original_timeout_s": timeout,
+                  "delegation.effective_timeout_s": effectiveTimeout,
+                  "delegation.parent_elapsed_ms": elapsed,
+                  "delegation.parent_remaining_ms": remaining,
+                  "delegation.parent_session_id": parentSessionId
+                });
+              }
+            }
+          }
           const result = await delegate({
             task,
-            timeout,
+            timeout: effectiveTimeout,
             debug,
             currentIteration: currentIteration || 0,
             maxIterations: maxIterations || 30,
@@ -101954,7 +102892,14 @@ var init_vercel = __esm({
             mcpConfigPath,
             delegationManager,
             // Per-instance delegation limits
-            parentAbortSignal
+            parentAbortSignal,
+            // Inherit timeout settings for subagent
+            timeoutBehavior,
+            requestTimeout,
+            gracefulTimeoutBonusSteps,
+            // Subagent lifecycle callbacks for graceful stop coordination
+            onSubagentCreated,
+            onSubagentCompleted
           });
           return result;
         }
@@ -103433,6 +104378,121 @@ var init_file_lister = __esm({
   }
 });
 
+// src/agent/otelLogBridge.js
+function getOtelApi() {
+  if (otelApiAttempted) return otelApi;
+  otelApiAttempted = true;
+  try {
+    otelApi = (function(name15) {
+      return _require(name15);
+    })("@opentelemetry/api");
+  } catch {
+  }
+  return otelApi;
+}
+function getOtelLogger() {
+  if (otelLoggerAttempted) return otelLogger;
+  otelLoggerAttempted = true;
+  try {
+    const { logs } = (function(name15) {
+      return _require(name15);
+    })("@opentelemetry/api-logs");
+    otelLogger = logs.getLogger("probe-agent");
+  } catch {
+  }
+  return otelLogger;
+}
+function getTraceSuffix() {
+  try {
+    const api2 = getOtelApi();
+    if (!api2) return "";
+    const span = api2.trace.getSpan(api2.context.active());
+    const ctx = span?.spanContext?.();
+    if (!ctx?.traceId) return "";
+    return ` [trace_id=${ctx.traceId} span_id=${ctx.spanId}]`;
+  } catch {
+    return "";
+  }
+}
+function emitOtelLog(msg, level) {
+  try {
+    const logger = getOtelLogger();
+    if (!logger) return;
+    const api2 = getOtelApi();
+    let traceId, spanId;
+    if (api2) {
+      const span = api2.trace.getSpan(api2.context.active());
+      const ctx = span?.spanContext?.();
+      if (ctx?.traceId) {
+        traceId = ctx.traceId;
+        spanId = ctx.spanId;
+      }
+    }
+    logger.emit({
+      severityNumber: OTEL_SEVERITY[level] || 9,
+      severityText: level.toUpperCase(),
+      body: msg,
+      attributes: {
+        "probe.logger": true,
+        ...traceId ? { trace_id: traceId, span_id: spanId } : {}
+      }
+    });
+  } catch {
+  }
+}
+function patchConsole() {
+  if (patched) return;
+  const methods = ["log", "info", "warn", "error"];
+  const c = globalThis.console;
+  for (const m of methods) {
+    const orig = c[m].bind(c);
+    originals[m] = orig;
+    c[m] = (...args) => {
+      const msgParts = args.map(
+        (a) => typeof a === "string" ? a : a instanceof Error ? a.message : JSON.stringify(a)
+      );
+      const msg = msgParts.join(" ");
+      emitOtelLog(msg, m === "log" ? "log" : m);
+      const suffix = getTraceSuffix();
+      if (suffix) {
+        if (typeof args[0] === "string") {
+          args[0] = args[0] + suffix;
+        } else {
+          args.push(suffix);
+        }
+      }
+      return orig(...args);
+    };
+  }
+  patched = true;
+}
+var import_module, _require, OTEL_SEVERITY, patched, originals, otelApi, otelApiAttempted, otelLogger, otelLoggerAttempted;
+var init_otelLogBridge = __esm({
+  "src/agent/otelLogBridge.js"() {
+    "use strict";
+    import_module = require("module");
+    _require = (0, import_module.createRequire)("file:///");
+    OTEL_SEVERITY = {
+      log: 9,
+      // INFO
+      info: 9,
+      // INFO
+      warn: 13,
+      // WARN
+      error: 17,
+      // ERROR
+      debug: 5
+      // DEBUG
+    };
+    patched = false;
+    originals = {};
+    otelApi = null;
+    otelApiAttempted = false;
+    otelLogger = null;
+    otelLoggerAttempted = false;
+  }
+});
+
 // src/agent/simpleTelemetry.js
 function initializeSimpleTelemetryFromOptions(options) {
   const telemetry = new SimpleTelemetry({
@@ -103441,6 +104501,7 @@ function initializeSimpleTelemetryFromOptions(options) {
     enableConsole: options.traceConsole,
     filePath: options.traceFile || "./traces.jsonl"
   });
+  patchConsole();
   return telemetry;
 }
 var import_fs15, import_path18, SimpleTelemetry, SimpleAppTracer;
@@ -103449,6 +104510,7 @@ var init_simpleTelemetry = __esm({
     "use strict";
     import_fs15 = require("fs");
     import_path18 = require("path");
+    init_otelLogBridge();
     SimpleTelemetry = class {
       constructor(options = {}) {
         this.serviceName = options.serviceName || "probe-agent";
@@ -103899,6 +104961,9 @@ var init_hooks = __esm({
 var index_exports = {};
 __export(index_exports, {
   DEFAULT_SYSTEM_MESSAGE: () => DEFAULT_SYSTEM_MESSAGE,
+  ENGINE_ACTIVITY_TIMEOUT_DEFAULT: () => ENGINE_ACTIVITY_TIMEOUT_DEFAULT,
+  ENGINE_ACTIVITY_TIMEOUT_MAX: () => ENGINE_ACTIVITY_TIMEOUT_MAX,
+  ENGINE_ACTIVITY_TIMEOUT_MIN: () => ENGINE_ACTIVITY_TIMEOUT_MIN,
   FileTracker: () => FileTracker,
   HOOK_TYPES: () => HOOK_TYPES,
   HookManager: () => HookManager,
@@ -103985,6 +105050,9 @@ init_index();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_SYSTEM_MESSAGE,
+  ENGINE_ACTIVITY_TIMEOUT_DEFAULT,
+  ENGINE_ACTIVITY_TIMEOUT_MAX,
+  ENGINE_ACTIVITY_TIMEOUT_MIN,
   FileTracker,
   HOOK_TYPES,
   HookManager,