@cognipeer/agent-sdk 0.6.5 → 0.7.0

package/dist/index.cjs

@@ -52,7 +52,7 @@ function getTokenCounter() {
 function countApproxTokens(text) {
   return activeTokenCounter(text || "");
 }
-function extractMessageText(m) {
+function extractMessageText2(m) {
   if (!m) return "";
   const parts = [];
   parts.push(m.role || "");
@@ -102,7 +102,7 @@ function extractMessageText(m) {
 }
 function countMessagesTokens(messages) {
   if (!Array.isArray(messages) || messages.length === 0) return 0;
-  const allText = messages.map(extractMessageText).join("\n");
+  const allText = messages.map(extractMessageText2).join("\n");
   return countApproxTokens(allText) + messages.length * 4;
 }
 var activeTokenCounter;
@@ -753,6 +753,7 @@ function createResolverNode() {
       toolHistory: state.toolHistory || [],
       toolHistoryArchived: state.toolHistoryArchived || [],
       pendingApprovals: state.pendingApprovals || [],
+      pendingUserQuestions: state.pendingUserQuestions || [],
       plan: state.plan || null,
       planVersion: state.planVersion || 0
     };
@@ -1271,6 +1272,7 @@ function eventToOtlpSpan(event) {
     stringAttr("cognipeer.actor.role", event.actor?.role),
     stringAttr("cognipeer.model", event.model),
     stringAttr("cognipeer.provider", event.provider),
+    stringAttr("cognipeer.tool.details", event.toolDetails ? JSON.stringify(event.toolDetails) : void 0),
     intAttr("cognipeer.tokens.input", event.inputTokens),
     intAttr("cognipeer.tokens.output", event.outputTokens),
     intAttr("cognipeer.tokens.total", event.totalTokens),
@@ -1742,6 +1744,7 @@ function recordTraceEvent(session, event) {
     responseBytes,
     model: resolvedModel,
     provider: resolvedProvider,
+    toolDetails: session.resolvedConfig.logData ? sanitizeTracePayload(event.toolDetails) : void 0,
     toolExecutionId: event.toolExecutionId,
     retryOf: event.retryOf,
     error: event.error ?? (status === "error" ? { message: "Unknown error" } : void 0) ?? void 0,
@@ -2192,16 +2195,99 @@ function createAgentCoreNode(opts) {
   };
 }
 
+// src/utils/content.ts
+function contentToString(content) {
+  try {
+    if (content == null) return "";
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content.map((p) => {
+        if (!p || typeof p !== "object") return String(p);
+        if (p.type === "text") return String(p.text ?? "");
+        if (p.type === "image_url") {
+          const img = p.image_url;
+          const url = typeof img === "string" ? img : img?.url;
+          const detail = typeof img === "string" ? void 0 : img?.detail;
+          return `[image:${url || "unknown"}${detail ? ` detail=${detail}` : ""}]`;
+        }
+        return JSON.stringify(p);
+      }).join("\n");
+    }
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+function mergeContentsToString(contents) {
+  return contents.map((c) => contentToString(c)).join("\n");
+}
+function safeStringify(value, pretty = false) {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, pretty ? 2 : void 0) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+function extractMessageText(message) {
+  if (!message) return "";
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => typeof part === "string" ? part : part?.text ?? part?.content ?? "").join("");
+  }
+  return "";
+}
+
+// src/utils/traceSections.ts
+function truncate(text, max = 500) {
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max)}\u2026` : text;
+}
+function summarizeToolOutput(output) {
+  if (output == null) return "";
+  if (typeof output === "string") return truncate(output.trim());
+  if (Array.isArray(output)) {
+    const preview = output.slice(0, 3).map((item, index) => `${index + 1}. ${truncate(safeStringify(item))}`).join("\n");
+    const suffix = output.length > 3 ? `
+\u2026 (+${output.length - 3} more)` : "";
+    return `${preview}${suffix}`.trim();
+  }
+  if (typeof output === "object") {
+    if (Array.isArray(output.items)) {
+      return summarizeToolOutput(output.items);
+    }
+    return truncate(safeStringify(output));
+  }
+  return truncate(String(output));
+}
+function extractToolItems(output) {
+  const source = Array.isArray(output) ? output : Array.isArray(output?.items) ? output.items : void 0;
+  if (!Array.isArray(source) || source.length === 0) return void 0;
+  return source.slice(0, 5).map((item) => {
+    if (item && typeof item === "object") {
+      const snippetSource = item.content ?? item.snippet ?? item.description ?? item.text ?? item.summary ?? item;
+      return {
+        title: typeof item.title === "string" ? item.title : void 0,
+        url: typeof item.url === "string" ? item.url : void 0,
+        snippet: truncate(safeStringify(snippetSource))
+      };
+    }
+    return { snippet: truncate(safeStringify(item)) };
+  });
+}
+
 // src/smart/runtimeConfig.ts
 var DEFAULT_CRITICAL_TOOLS = ["response", "manage_todo_list", "get_tool_response"];
 var BASE_DEFAULTS = {
-  limits: { maxToolCalls: 8, maxParallelTools: 2, maxContextTokens: 24e3, maxTotalOutputTokens: 0, maxCostUsd: 0, maxWallClockMs: 0 },
+  limits: { maxToolCalls: 20, maxParallelTools: 5, maxContextTokens: 96e3, maxTotalOutputTokens: 0, maxCostUsd: 0, maxWallClockMs: 0 },
   summarization: {
     enable: true,
-    maxTokens: 24e3,
-    summaryTriggerTokens: 17e3,
-    summaryPromptMaxTokens: 7e3,
-    summaryCompressionRatioTarget: 0.35,
+    maxTokens: 96e3,
+    summaryTriggerTokens: 72e3,
+    summaryPromptMaxTokens: 12e3,
+    summaryCompressionRatioTarget: 0.45,
     summaryMode: "incremental",
     promptTemplate: "",
     toolFreeCall: true,
@@ -2209,13 +2295,13 @@ var BASE_DEFAULTS = {
   },
   context: {
     policy: "hybrid",
-    lastTurnsToKeep: 8,
+    lastTurnsToKeep: 16,
     toolResponsePolicy: "summarize_archive",
     budget: {
-      systemReserveTokens: 1200,
-      goalsReserveTokens: 1200,
-      recentTurnsReserveTokens: 5200,
-      toolResponseReserveTokens: 2800
+      systemReserveTokens: 2e3,
+      goalsReserveTokens: 2e3,
+      recentTurnsReserveTokens: 18e3,
+      toolResponseReserveTokens: 9e3
     }
   },
   planning: {
@@ -2232,14 +2318,14 @@ var BASE_DEFAULTS = {
   delegation: {
     mode: "role_based",
     maxDelegationDepth: 2,
-    maxChildCalls: 4,
-    maxParallelChild: 2,
+    maxChildCalls: 6,
+    maxParallelChild: 3,
     childContextPolicy: "scoped",
     requireJsonOutputContract: true
   },
   toolResponses: {
-    maxToolResponseChars: 12e3,
-    maxToolResponseTokens: 3e3,
+    maxToolResponseChars: 32e3,
+    maxToolResponseTokens: 8e3,
     defaultPolicy: "summarize_archive",
     toolResponseRetentionByTool: {},
     criticalTools: [...DEFAULT_CRITICAL_TOOLS],
@@ -2268,54 +2354,54 @@ function buildProfile(overrides) {
 }
 var DEFAULT_PROFILE_CONFIGS = {
   fast: buildProfile({
-    limits: { maxToolCalls: 4, maxParallelTools: 1, maxContextTokens: 12e3 },
+    limits: { maxToolCalls: 8, maxParallelTools: 3, maxContextTokens: 32e3 },
     summarization: {
-      maxTokens: 12e3,
-      summaryTriggerTokens: 9e3,
-      summaryPromptMaxTokens: 5e3,
-      summaryCompressionRatioTarget: 0.4
+      maxTokens: 32e3,
+      summaryTriggerTokens: 24e3,
+      summaryPromptMaxTokens: 6e3,
+      summaryCompressionRatioTarget: 0.5
     },
     context: {
-      lastTurnsToKeep: 6,
+      lastTurnsToKeep: 8,
       toolResponsePolicy: "keep_structured",
-      budget: { systemReserveTokens: 1e3, goalsReserveTokens: 900, recentTurnsReserveTokens: 3200, toolResponseReserveTokens: 1800 }
+      budget: { systemReserveTokens: 1500, goalsReserveTokens: 1200, recentTurnsReserveTokens: 6e3, toolResponseReserveTokens: 3500 }
     },
     memory: { readPolicy: "recent_only" },
     delegation: { mode: "off", maxDelegationDepth: 1, maxChildCalls: 2, maxParallelChild: 1, childContextPolicy: "minimal" },
-    toolResponses: { maxToolResponseChars: 8e3, maxToolResponseTokens: 2e3 }
+    toolResponses: { maxToolResponseChars: 16e3, maxToolResponseTokens: 4e3 }
   }),
   balanced: buildProfile({}),
   deep: buildProfile({
-    limits: { maxToolCalls: 14, maxParallelTools: 3, maxContextTokens: 42e3 },
+    limits: { maxToolCalls: 40, maxParallelTools: 8, maxContextTokens: 2e5 },
     summarization: {
-      maxTokens: 42e3,
-      summaryTriggerTokens: 3e4,
-      summaryPromptMaxTokens: 9e3,
-      summaryCompressionRatioTarget: 0.3
+      maxTokens: 2e5,
+      summaryTriggerTokens: 15e4,
+      summaryPromptMaxTokens: 16e3,
+      summaryCompressionRatioTarget: 0.4
     },
     context: {
-      lastTurnsToKeep: 12,
-      budget: { systemReserveTokens: 1400, goalsReserveTokens: 1600, recentTurnsReserveTokens: 7e3, toolResponseReserveTokens: 3600 }
+      lastTurnsToKeep: 30,
+      budget: { systemReserveTokens: 2500, goalsReserveTokens: 2500, recentTurnsReserveTokens: 36e3, toolResponseReserveTokens: 18e3 }
     },
     memory: { scope: "workspace" },
-    delegation: { maxDelegationDepth: 3, maxChildCalls: 6 },
-    toolResponses: { maxToolResponseChars: 16e3, maxToolResponseTokens: 4e3 }
+    delegation: { maxDelegationDepth: 3, maxChildCalls: 10, maxParallelChild: 4 },
+    toolResponses: { maxToolResponseChars: 64e3, maxToolResponseTokens: 16e3 }
   }),
   research: buildProfile({
-    limits: { maxToolCalls: 20, maxParallelTools: 4, maxContextTokens: 56e3 },
+    limits: { maxToolCalls: 80, maxParallelTools: 10, maxContextTokens: 4e5 },
     summarization: {
-      maxTokens: 56e3,
-      summaryTriggerTokens: 42e3,
-      summaryPromptMaxTokens: 1e4,
-      summaryCompressionRatioTarget: 0.28
+      maxTokens: 4e5,
+      summaryTriggerTokens: 3e5,
+      summaryPromptMaxTokens: 24e3,
+      summaryCompressionRatioTarget: 0.35
     },
     context: {
-      lastTurnsToKeep: 20,
-      budget: { systemReserveTokens: 1600, goalsReserveTokens: 1800, recentTurnsReserveTokens: 9e3, toolResponseReserveTokens: 4800 }
+      lastTurnsToKeep: 60,
+      budget: { systemReserveTokens: 3e3, goalsReserveTokens: 3e3, recentTurnsReserveTokens: 72e3, toolResponseReserveTokens: 32e3 }
     },
     memory: { scope: "workspace" },
-    delegation: { mode: "automatic", maxDelegationDepth: 4, maxChildCalls: 8, maxParallelChild: 3, childContextPolicy: "full" },
-    toolResponses: { maxToolResponseChars: 24e3, maxToolResponseTokens: 6e3 }
+    delegation: { mode: "automatic", maxDelegationDepth: 4, maxChildCalls: 16, maxParallelChild: 6, childContextPolicy: "full" },
+    toolResponses: { maxToolResponseChars: 96e3, maxToolResponseTokens: 24e3 }
   })
 };
 function mergeLimits(base, override) {
@@ -2405,53 +2491,6 @@ function getResolvedSmartConfig(opts, runtime) {
 
 // src/smart/toolResponses.ts
 init_utilTokens();
-
-// src/utils/content.ts
-function contentToString(content) {
-  try {
-    if (content == null) return "";
-    if (typeof content === "string") return content;
-    if (Array.isArray(content)) {
-      return content.map((p) => {
-        if (!p || typeof p !== "object") return String(p);
-        if (p.type === "text") return String(p.text ?? "");
-        if (p.type === "image_url") {
-          const img = p.image_url;
-          const url = typeof img === "string" ? img : img?.url;
-          const detail = typeof img === "string" ? void 0 : img?.detail;
-          return `[image:${url || "unknown"}${detail ? ` detail=${detail}` : ""}]`;
-        }
-        return JSON.stringify(p);
-      }).join("\n");
-    }
-    return JSON.stringify(content);
-  } catch {
-    return String(content);
-  }
-}
-function mergeContentsToString(contents) {
-  return contents.map((c) => contentToString(c)).join("\n");
-}
-function safeStringify(value, pretty = false) {
-  if (value == null) return "";
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value, null, pretty ? 2 : void 0) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}
-function extractMessageText2(message) {
-  if (!message) return "";
-  const content = message.content;
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content.map((part) => typeof part === "string" ? part : part?.text ?? part?.content ?? "").join("");
-  }
-  return "";
-}
-
-// src/smart/toolResponses.ts
 function summarizeObject(value) {
   if (value == null) return "null";
   if (typeof value === "string") {
@@ -2566,6 +2605,97 @@ function normalizeToolCall(call) {
     args: call.args ?? call.arguments ?? call.input ?? call.function?.arguments ?? call.function_call?.arguments
   };
 }
+function normalizeToolSchema(tool, toolName) {
+  const schema = tool.schema;
+  if (!schema) return void 0;
+  if (typeof schema === "object" && schema._def) {
+    try {
+      return sanitizeTracePayload(zodToJsonSchema.zodToJsonSchema(schema, { name: toolName }));
+    } catch {
+    }
+  }
+  if (schema && typeof schema === "object" && typeof schema.toJSON === "function") {
+    try {
+      return sanitizeTracePayload(schema.toJSON());
+    } catch {
+    }
+  }
+  return sanitizeTracePayload(schema);
+}
+function buildToolDetails(tool, toolName) {
+  if (!tool) return void 0;
+  const details = { name: toolName };
+  if (typeof tool.description === "string" && tool.description.trim().length > 0) {
+    details.description = tool.description;
+  }
+  const inputSchema = normalizeToolSchema(tool, toolName);
+  if (inputSchema !== void 0) details.inputSchema = inputSchema;
+  const needsApproval = typeof tool.needsApproval === "boolean" ? tool.needsApproval : void 0;
+  if (needsApproval !== void 0 || tool.approvalPrompt !== void 0 || tool.approvalDefaults !== void 0) {
+    details.approval = {
+      required: needsApproval,
+      prompt: typeof tool.approvalPrompt === "string" ? tool.approvalPrompt : void 0,
+      defaults: tool.approvalDefaults !== void 0 ? sanitizeTracePayload(tool.approvalDefaults) : void 0
+    };
+  }
+  const cache = tool.cache;
+  if (cache !== void 0) {
+    details.cache = {
+      enabled: Boolean(cache),
+      scope: cache && typeof cache === "object" && typeof cache.scope === "string" ? cache.scope : void 0,
+      ttlMs: cache && typeof cache === "object" && typeof cache.ttlMs === "number" ? cache.ttlMs : void 0,
+      hasKeyFn: Boolean(cache && typeof cache === "object" && typeof cache.keyFn === "function")
+    };
+  }
+  const retry = tool.retry;
+  if (retry && typeof retry === "object") {
+    details.retry = {
+      maxRetries: typeof retry.maxRetries === "number" ? retry.maxRetries : void 0,
+      backoffMs: typeof retry.backoffMs === "number" ? retry.backoffMs : void 0,
+      circuitBreakerThreshold: typeof retry.circuitBreakerThreshold === "number" ? retry.circuitBreakerThreshold : void 0,
+      hasShouldRetry: typeof retry.shouldRetry === "function"
+    };
+  }
+  if (tool.maxExecutionsPerRun !== void 0) {
+    details.limits = { maxExecutionsPerRun: tool.maxExecutionsPerRun };
+  }
+  if (typeof tool.__source === "string") {
+    details.source = tool.__source;
+  }
+  return details;
+}
+function buildToolTraceSections(params) {
+  const sanitizedArgs = sanitizeTracePayload(params.args ?? {});
+  const sanitizedOutput = sanitizeTracePayload(params.output);
+  const summary = params.summary ?? summarizeToolOutput(sanitizedOutput);
+  const items = extractToolItems(sanitizedOutput);
+  return [
+    {
+      kind: "tool_call",
+      label: `Tool Call: ${params.toolName}`,
+      tool: params.toolName,
+      arguments: sanitizedArgs,
+      toolDetails: params.toolDetails
+    },
+    {
+      kind: "tool_result",
+      label: `Tool Result: ${params.toolName}`,
+      tool: params.toolName,
+      summary,
+      items,
+      output: sanitizedOutput,
+      toolDetails: params.toolDetails,
+      execution: {
+        id: params.executionId,
+        status: params.status,
+        durationMs: params.durationMs,
+        fromCache: params.fromCache
+      },
+      classification: params.classification,
+      retentionPolicy: params.retentionPolicy
+    }
+  ];
+}
 function createToolsNode(initialTools, opts) {
   return async (state) => {
     const runtime = state.agent || {
@@ -2594,13 +2724,16 @@ function createToolsNode(initialTools, opts) {
     const traceSession = state.ctx?.__traceSession;
     const pendingApprovals = Array.isArray(state.pendingApprovals) ? state.pendingApprovals.map((entry) => ({ ...entry })) : [];
     const pendingByCallId = new Map(pendingApprovals.map((entry) => [entry.toolCallId, entry]));
+    const pendingUserQuestions = Array.isArray(state.pendingUserQuestions) ? state.pendingUserQuestions.map((entry) => ({ ...entry })) : [];
     let awaitingApproval = false;
+    let awaitingUserQuestion = false;
     for (const tool of toolByName.values()) {
       const anyTool = tool;
       if (anyTool._stateRef && typeof anyTool._stateRef === "object") {
         anyTool._stateRef.toolHistory = state.toolHistory;
         anyTool._stateRef.toolHistoryArchived = state.toolHistoryArchived;
         anyTool._stateRef.pendingApprovals = pendingApprovals;
+        anyTool._stateRef.pendingUserQuestions = pendingUserQuestions;
         anyTool._stateRef.messages = state.messages;
         anyTool._stateRef.ctx = state.ctx || (state.ctx = {});
         anyTool._stateRef.__onEvent = onEvent;
@@ -2671,9 +2804,11 @@ function createToolsNode(initialTools, opts) {
         args = validatedArgs.value;
       }
       const toolName = tool.name || tc.name;
+      const toolDetails = buildToolDetails(tool, toolName);
       const toolStateRef = tool._stateRef && typeof tool._stateRef === "object" ? tool._stateRef : null;
       if (toolStateRef) {
         toolStateRef.pendingApprovals = pendingApprovals;
+        toolStateRef.pendingUserQuestions = pendingUserQuestions;
         toolStateRef.ctx = state.ctx || (state.ctx = {});
         toolStateRef.__currentToolCallId = toolCallId;
         delete toolStateRef.__awaitingApproval;
@@ -2690,21 +2825,17 @@ function createToolsNode(initialTools, opts) {
             label: `Tool Skipped - ${toolName}`,
             actor: { scope: "tool", name: toolName, role: "tool" },
             status: "skipped",
+            toolDetails,
             toolExecutionId: tc.id,
-            messageList: [
-              {
-                role: "assistant",
-                name: toolName,
-                content: limitMessage,
-                tool_calls: [
-                  {
-                    id: tc.id,
-                    type: "function",
-                    function: { name: toolName, arguments: sanitizeTracePayload(args) }
-                  }
-                ]
-              }
-            ]
+            sections: buildToolTraceSections({
+              args,
+              executionId: tc.id,
+              output: limitMessage,
+              status: "skipped",
+              summary: limitMessage,
+              toolDetails,
+              toolName
+            })
           });
           toolCount += 1;
           return { status: "error" };
@@ -2791,6 +2922,25 @@ function createToolsNode(initialTools, opts) {
         push({ role: "tool", content: breakerMsg, tool_call_id: toolCallId, name: tc.name });
         markToolFailure(breakerMsg, toolName, toolCallId);
         onEvent?.({ type: "tool_call", phase: "error", name: toolName, id: tc.id, args, error: { message: breakerMsg } });
+        recordTraceEvent(traceSession, {
+          type: "tool_call",
+          label: `Tool Error - ${toolName}`,
+          actor: { scope: "tool", name: toolName, role: "tool" },
+          status: "error",
+          requestBytes: inputBytes,
+          toolDetails,
+          toolExecutionId: toolCallId,
+          error: { message: breakerMsg },
+          sections: buildToolTraceSections({
+            args,
+            executionId: toolCallId,
+            output: { message: breakerMsg },
+            status: "error",
+            summary: breakerMsg,
+            toolDetails,
+            toolName
+          })
+        });
         toolCount += 1;
         return { status: "error" };
       }
@@ -2815,6 +2965,38 @@ function createToolsNode(initialTools, opts) {
           });
           push({ role: "tool", content: responsePolicy2.content, tool_call_id: tc.id || `${tc.name}_${toolCount}`, name: tc.name });
           onEvent?.({ type: "tool_call", phase: "success", name: toolName, id: tc.id, args, result: cachedHit, durationMs: 0 });
+          const sanitizedCachedHit = sanitizeTracePayload(cachedHit);
+          const outputBytes2 = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedCachedHit) : void 0;
+          recordTraceEvent(traceSession, {
+            type: "tool_call",
+            label: `Tool Execution - ${toolName}`,
+            actor: { scope: "tool", name: toolName, role: "tool" },
+            durationMs: 0,
+            requestBytes: inputBytes,
+            responseBytes: outputBytes2,
+            toolDetails,
+            toolExecutionId: executionId2,
+            sections: buildToolTraceSections({
+              args,
+              classification: responsePolicy2.classification,
+              durationMs: 0,
+              executionId: executionId2,
+              fromCache: true,
+              output: sanitizedCachedHit,
+              retentionPolicy: "keep_full",
+              status: "cached",
+              summary: responsePolicy2.content,
+              toolDetails,
+              toolName
+            }),
+            debug: {
+              classification: responsePolicy2.classification,
+              retentionPolicy: "keep_full",
+              originalTokenCount: responsePolicy2.tokenCount,
+              truncated: responsePolicy2.truncated,
+              fromCache: true
+            }
+          });
           toolCount += 1;
           return { status: "success" };
         }
@@ -2885,6 +3067,22 @@ function createToolsNode(initialTools, opts) {
             approval: pendingApproval
           };
         }
+        if (output && typeof output === "object" && output.__awaitingUserQuestion) {
+          if (toolStateRef?.ctx && typeof toolStateRef.ctx === "object") {
+            state.ctx = toolStateRef.ctx;
+          }
+          const pendingQuestion = pendingUserQuestions.find(
+            (entry) => entry.toolCallId === output.toolCallId || entry.id === output.id
+          );
+          if (!pendingQuestion) {
+            throw new Error(`Tool ${toolName} requested a user question but no pending question entry was recorded.`);
+          }
+          awaitingUserQuestion = true;
+          return {
+            status: "awaiting_user_question",
+            userQuestion: pendingQuestion
+          };
+        }
         if (output && typeof output === "object" && output.__finalStructuredOutput) {
           if (!state.ctx) state.ctx = {};
           state.ctx.__structuredOutputParsed = output.data;
@@ -2919,28 +3117,6 @@ function createToolsNode(initialTools, opts) {
         }
         const sanitizedOutput = sanitizeTracePayload(output);
         const outputBytes = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedOutput) : void 0;
-        const messageList = [
-          {
-            role: "assistant",
-            name: toolName,
-            content: "",
-            tool_calls: [
-              {
-                id: tc.id || executionId,
-                type: "function",
-                function: {
-                  name: toolName,
-                  arguments: sanitizedArgs
-                }
-              }
-            ]
-          },
-          {
-            role: "tool",
-            name: toolName,
-            content: responsePolicy.content
-          }
-        ];
         recordTraceEvent(traceSession, {
           type: "tool_call",
           label: `Tool Execution - ${toolName}`,
@@ -2948,8 +3124,20 @@ function createToolsNode(initialTools, opts) {
           durationMs,
           requestBytes: inputBytes,
           responseBytes: outputBytes,
+          toolDetails,
           toolExecutionId: executionId,
-          messageList,
+          sections: buildToolTraceSections({
+            args: sanitizedArgs,
+            classification: responsePolicy.classification,
+            durationMs,
+            executionId,
+            output: sanitizedOutput,
+            retentionPolicy: "keep_full",
+            status: "success",
+            summary: responsePolicy.content,
+            toolDetails,
+            toolName
+          }),
           debug: {
             classification: responsePolicy.classification,
             retentionPolicy: "keep_full",
@@ -2968,6 +3156,7 @@ function createToolsNode(initialTools, opts) {
         markToolFailure(message, toolName, toolCallId);
         onEvent?.({ type: "tool_call", phase: "error", name: toolName, id: tc.id, args, error: { message } });
         onProgress?.({ stage: "tools", message: `Tool ${tc.name} failed`, detail: { error: message } });
+        const errorOutput = { message, stack: error?.stack };
         recordTraceEvent(traceSession, {
           type: "tool_call",
           label: `Tool Error - ${toolName}`,
@@ -2975,27 +3164,20 @@ function createToolsNode(initialTools, opts) {
           status: "error",
           durationMs,
           requestBytes: inputBytes,
+          responseBytes: traceSession?.resolvedConfig.logData ? estimatePayloadBytes(errorOutput) : void 0,
+          toolDetails,
           toolExecutionId: executionId,
           error: { message, stack: error?.stack },
-          messageList: [
-            {
-              role: "assistant",
-              name: toolName,
-              content: "",
-              tool_calls: [
-                {
-                  id: tc.id || executionId,
-                  type: "function",
-                  function: { name: toolName, arguments: sanitizedArgs }
-                }
-              ]
-            },
-            {
-              role: "tool",
-              name: toolName,
-              content: `Error executing tool: ${message}`
-            }
-          ]
+          sections: buildToolTraceSections({
+            args: sanitizedArgs,
+            durationMs,
+            executionId,
+            output: errorOutput,
+            status: "error",
+            summary: `Error executing tool: ${message}`,
+            toolDetails,
+            toolName
+          })
         });
         toolCount += 1;
         return { status: "error", approval: approvalEntry };
@@ -3022,15 +3204,19 @@ function createToolsNode(initialTools, opts) {
       return false;
     };
     for (const idx of approvalIndices) {
-      if (awaitingApproval || shouldStop) break;
+      if (awaitingApproval || awaitingUserQuestion || shouldStop) break;
       if (checkCancellationStop()) break;
       const result = await runOne(planned[idx], orderedSlots[idx]);
       if (result.status === "awaiting_approval") {
         awaitingApproval = true;
         break;
       }
+      if (result.status === "awaiting_user_question") {
+        awaitingUserQuestion = true;
+        break;
+      }
     }
-    if (!awaitingApproval && !shouldStop && parallelIndices.length > 0) {
+    if (!awaitingApproval && !awaitingUserQuestion && !shouldStop && parallelIndices.length > 0) {
       const concurrency = Math.max(1, Math.min(limits.maxParallelTools, parallelIndices.length));
       let cursor = 0;
       const workerError = {};
@@ -3038,7 +3224,7 @@ function createToolsNode(initialTools, opts) {
       for (let w = 0; w < concurrency; w++) {
         workers.push((async () => {
           while (true) {
-            if (workerError.err || shouldStop || awaitingApproval) return;
+            if (workerError.err || shouldStop || awaitingApproval || awaitingUserQuestion) return;
             const i = cursor++;
             if (i >= parallelIndices.length) return;
             if (checkCancellationStop()) return;
@@ -3049,6 +3235,10 @@ function createToolsNode(initialTools, opts) {
                 awaitingApproval = true;
                 return;
               }
+              if (result.status === "awaiting_user_question") {
+                awaitingUserQuestion = true;
+                return;
+              }
             } catch (err) {
               workerError.err = err;
               return;
@@ -3064,29 +3254,26 @@ function createToolsNode(initialTools, opts) {
     }
     for (const tc of skipped) {
       onEvent?.({ type: "tool_call", phase: "skipped", name: tc.name, id: tc.id, args: tc.args });
-      const sanitizedArgs = sanitizeTracePayload(tc.args);
+      const toolDetails = buildToolDetails(toolByName.get(tc.name), tc.name);
+      const skipMessage = `Skipped tool due to tool-call limit: ${tc.name}`;
       recordTraceEvent(traceSession, {
         type: "tool_call",
         label: `Tool Skipped - ${tc.name}`,
         actor: { scope: "tool", name: tc.name, role: "tool" },
         status: "skipped",
+        toolDetails,
         toolExecutionId: tc.id,
-        messageList: [
-          {
-            role: "assistant",
-            name: tc.name,
-            content: `Skipped tool due to tool-call limit: ${tc.name}`,
-            tool_calls: [
-              {
-                id: tc.id,
-                type: "function",
-                function: { name: tc.name, arguments: sanitizedArgs }
-              }
-            ]
-          }
-        ]
+        sections: buildToolTraceSections({
+          args: tc.args,
+          executionId: tc.id,
+          output: skipMessage,
+          status: "skipped",
+          summary: skipMessage,
+          toolDetails,
+          toolName: tc.name
+        })
       });
-      appended.push({ role: "tool", content: `Skipped tool due to tool-call limit: ${tc.name}`, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
+      appended.push({ role: "tool", content: skipMessage, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
       toolCount += 1;
     }
     if (!awaitingApproval && state.ctx?.__awaitingApproval) {
@@ -3111,11 +3298,12 @@ function createToolsNode(initialTools, opts) {
       toolCache: state.toolCache,
       // Explicitly propagate ctx so callers using `{ ...state, ...delta }`
       // do not silently capture a stale ctx reference. Mutations to
-      // __summarizationExhausted / __awaitingApproval / __structuredOutputParsed
-      // are made on this object during execution.
+      // __summarizationExhausted / __awaitingApproval / __awaitingUserQuestion /
+      // __structuredOutputParsed are made on this object during execution.
       ctx: state.ctx,
       agent: state.agent,
-      pendingApprovals
+      pendingApprovals,
+      pendingUserQuestions
     };
   };
 }
@@ -3581,6 +3769,226 @@ function resolveToolApprovalState(state, resolution) {
   };
 }
 
+// src/utils/userQuestions.ts
+var cloneQuestions = (questions) => Array.isArray(questions) ? questions.map((entry) => ({ ...entry })) : [];
+function validateAnswers(entry, answers, cancelled) {
+  if (cancelled) {
+    return answers || {};
+  }
+  const allowFreeText = entry.allowFreeText !== false;
+  const out = {};
+  const provided = answers || {};
+  for (const question of entry.questions) {
+    const required = question.required !== false;
+    const key = question.question;
+    const answer = provided[key] ?? provided[question.header || ""];
+    if (!answer) {
+      if (required) {
+        throw new Error(`Missing answer for required question: "${key}".`);
+      }
+      continue;
+    }
+    const values = Array.isArray(answer.values) ? answer.values.filter((v) => typeof v === "string") : [];
+    const freeText = typeof answer.freeText === "string" ? answer.freeText.trim() : "";
+    const notes = typeof answer.notes === "string" ? answer.notes : void 0;
+    if (freeText && !allowFreeText) {
+      throw new Error(
+        `Free-text answers are disabled for this agent (question: "${key}"). Pick one of the provided options.`
+      );
+    }
+    if (values.length === 0 && !freeText) {
+      if (required) {
+        throw new Error(`Question "${key}" requires either a selected option or free-text answer.`);
+      }
+      continue;
+    }
+    if (values.length > 1 && !question.multiSelect) {
+      throw new Error(`Question "${key}" is single-select but received multiple values.`);
+    }
+    if (Array.isArray(question.options) && question.options.length > 0 && values.length > 0) {
+      const allowedValues = new Set(
+        question.options.map((option) => option.value ?? option.label)
+      );
+      for (const value of values) {
+        if (!allowedValues.has(value)) {
+          if (!allowFreeText) {
+            throw new Error(
+              `Value "${value}" is not one of the allowed options for question "${key}".`
+            );
+          }
+        }
+      }
+    }
+    out[key] = { values, ...freeText ? { freeText } : {}, ...notes ? { notes } : {} };
+  }
+  return out;
+}
+function buildToolResponseContent(entry, answers, cancelled, notes) {
+  if (cancelled) {
+    return JSON.stringify({
+      status: "cancelled",
+      message: notes || "User dismissed the question without answering."
+    });
+  }
+  const payload = {
+    status: "answered",
+    answers: entry.questions.map((question) => {
+      const key = question.question;
+      const ans = answers[key];
+      return {
+        question: key,
+        header: question.header,
+        values: ans?.values ?? [],
+        freeText: ans?.freeText,
+        notes: ans?.notes
+      };
+    }),
+    ...notes ? { reviewerNotes: notes } : {}
+  };
+  return JSON.stringify(payload);
+}
+function resolveUserQuestionState(state, resolution) {
+  const pending = cloneQuestions(state.pendingUserQuestions);
+  const matchIndex = pending.findIndex(
+    (entry2) => entry2.id === resolution.id || entry2.toolCallId === resolution.id
+  );
+  if (matchIndex === -1) {
+    throw new Error(`Pending user question not found for id: ${resolution.id}`);
+  }
+  const entry = { ...pending[matchIndex] };
+  if (entry.status === "answered" || entry.status === "executed" || entry.status === "cancelled") {
+    throw new Error(`User question ${entry.id} already resolved (status: ${entry.status}).`);
+  }
+  const cancelled = resolution.cancelled === true;
+  const validated = validateAnswers(entry, resolution.answers, cancelled);
+  entry.status = cancelled ? "cancelled" : "answered";
+  entry.answers = validated;
+  entry.cancelled = cancelled || void 0;
+  entry.answeredBy = resolution.answeredBy;
+  entry.notes = resolution.notes;
+  entry.answeredAt = (/* @__PURE__ */ new Date()).toISOString();
+  pending[matchIndex] = entry;
+  const ctx = { ...state.ctx || {} };
+  delete ctx.__awaitingUserQuestion;
+  if (ctx.__resumeStage === "tools") {
+    delete ctx.__resumeStage;
+  }
+  ctx.__userQuestionResolved = { id: entry.id, status: entry.status };
+  const toolMessage = {
+    role: "tool",
+    name: "ask_user_question",
+    tool_call_id: entry.toolCallId,
+    content: buildToolResponseContent(entry, validated, cancelled, resolution.notes)
+  };
+  return {
+    ...state,
+    pendingUserQuestions: pending,
+    messages: [...state.messages || [], toolMessage],
+    ctx
+  };
+}
+var DEFAULT_DESCRIPTION_WITH_FREETEXT = "Pause the agent and surface a structured prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Prefer concrete options the user can pick over open-ended free-text \u2014 list `options` whenever you can anticipate the choices. The user may type a custom answer for any question. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user answers, their selections come back as the tool result.";
+var DEFAULT_DESCRIPTION_NO_FREETEXT = "Pause the agent and surface a structured multi-choice prompt to the human user when you genuinely cannot proceed without their input. Group up to 4 closely related questions into a single call. Every question MUST include at least two `options` \u2014 free-text answers are disabled for this agent. Do not use this tool for things you can deduce from the conversation, the system prompt, or another tool. After the user picks, their selections come back as the tool result.";
+function buildOptionSchema() {
+  return zod.z.object({
+    label: zod.z.string().min(1).describe("Display text the user sees"),
+    value: zod.z.string().min(1).optional().describe("Value returned in the answer; defaults to label"),
+    description: zod.z.string().optional(),
+    preview: zod.z.string().optional().describe("Optional code / ASCII preview rendered when this option is focused")
+  }).strict();
+}
+function buildQuestionSchema(allowFreeText) {
+  const optionSchema = buildOptionSchema();
+  const baseShape = {
+    question: zod.z.string().min(1).describe("Full question shown to the user"),
+    header: zod.z.string().max(40).optional().describe("Short chip / tag rendered next to the question (max ~12 chars recommended)"),
+    multiSelect: zod.z.boolean().optional().describe("Allow multiple selections. Default: false"),
+    placeholder: zod.z.string().optional(),
+    required: zod.z.boolean().optional().describe("Default: true")
+  };
+  if (allowFreeText) {
+    return zod.z.object({
+      ...baseShape,
+      options: zod.z.array(optionSchema).min(2).max(12).optional()
+    }).strict();
+  }
+  return zod.z.object({
+    ...baseShape,
+    options: zod.z.array(optionSchema).min(2).max(12).describe("Required: free-text answers are disabled for this agent")
+  }).strict();
+}
+function createAskUserQuestionTool(stateRef, config) {
+  const allowFreeText = config.allowFreeText !== false;
+  const description = config.promptOverride ?? (allowFreeText ? DEFAULT_DESCRIPTION_WITH_FREETEXT : DEFAULT_DESCRIPTION_NO_FREETEXT);
+  const questionSchema = buildQuestionSchema(allowFreeText);
+  const askUser = createTool({
+    name: "ask_user_question",
+    description,
+    schema: zod.z.object({
+      questions: zod.z.array(questionSchema).min(1).max(4).describe("1-4 related questions to ask in a single pause.")
+    }).strict(),
+    func: async ({ questions }) => {
+      const ref = askUser._stateRef || (askUser._stateRef = {});
+      const onEvent = ref.__onEvent;
+      if (!ref.ctx) ref.ctx = {};
+      const ctx = ref.ctx;
+      const toolCallId = ref.__currentToolCallId || `ask_user_${nanoid.nanoid(6)}`;
+      if (!ref.pendingUserQuestions) ref.pendingUserQuestions = [];
+      const pendingList = ref.pendingUserQuestions;
+      const entry = {
+        id: nanoid.nanoid(),
+        toolCallId,
+        toolName: "ask_user_question",
+        questions,
+        status: "pending",
+        requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        allowFreeText
+      };
+      pendingList.push(entry);
+      ctx.__awaitingUserQuestion = {
+        id: entry.id,
+        toolCallId: entry.toolCallId,
+        requestedAt: entry.requestedAt
+      };
+      ctx.__resumeStage = "tools";
+      onEvent?.({
+        type: "user_question",
+        status: "pending",
+        id: entry.id,
+        toolCallId: entry.toolCallId,
+        questions: entry.questions,
+        allowFreeText
+      });
+      recordTraceEvent(ctx.__traceSession, {
+        type: "user_question",
+        label: "Ask User",
+        actor: { scope: "agent", name: "ask_user_question", role: "user_interaction" },
+        status: "success",
+        sections: [
+          {
+            kind: "metadata",
+            label: "Pending Question",
+            data: {
+              id: entry.id,
+              toolCallId: entry.toolCallId,
+              questions: entry.questions,
+              allowFreeText
+            }
+          }
+        ]
+      });
+      return {
+        __awaitingUserQuestion: true,
+        id: entry.id,
+        toolCallId: entry.toolCallId
+      };
+    }
+  });
+  askUser._stateRef = stateRef;
+  askUser.__source = "human-in-the-loop";
+  return askUser;
+}
+
 // src/agent.ts
 init_utilTokens();
 
@@ -3792,6 +4200,21 @@ function createAgent(opts) {
   const resolver = createResolverNode();
   const agentCore = createAgentCoreNode(opts);
   const toolsBase = [...opts.tools ?? []];
+  const askUserConfig = (() => {
+    const raw = opts.humanInTheLoop?.askUser;
+    if (!raw) return void 0;
+    if (raw === true) return { enabled: true, allowFreeText: true };
+    return {
+      enabled: true,
+      allowFreeText: raw.allowFreeText !== false,
+      promptOverride: raw.promptOverride
+    };
+  })();
+  const askUserOnQuestion = typeof opts.humanInTheLoop?.askUser === "object" ? opts.humanInTheLoop?.askUser?.onQuestion : void 0;
+  const askUserStateRef = askUserConfig ? { pendingUserQuestions: void 0, ctx: void 0, __onEvent: void 0, __currentToolCallId: void 0 } : void 0;
+  if (askUserConfig && askUserStateRef) {
+    toolsBase.push(createAskUserQuestionTool(askUserStateRef, askUserConfig));
+  }
   const soManager = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   if (soManager) {
     const modelCapabilities = getModelCapabilities(opts.model);
@@ -3836,7 +4259,8 @@ function createAgent(opts) {
     useTodoList: void 0,
     outputSchema: opts.outputSchema,
     responseFormat: soManager?.getResponseFormat(),
-    tracing: opts.tracing
+    tracing: opts.tracing,
+    humanInTheLoop: askUserConfig ? { askUser: askUserConfig } : void 0
   };
   const summarizationThreshold = getActiveSummarizationThreshold(opts);
   async function runLoop(initial, config, emit) {
@@ -4100,7 +4524,7 @@ function createAgent(opts) {
       if (toolCalls.length === 0) {
         if (soManager && !state.ctx?.__finalizedDueToStructuredOutput && !state.ctx?.__structuredOutputForceFinalize) {
           if (soManager.strategy.kind === "native") {
-            const assistantText = extractMessageText2(lastMsg);
+            const assistantText = extractMessageText(lastMsg);
             if (assistantText) {
               const parsed = soManager.parseFromContent(assistantText);
               if (parsed.success) {
@@ -4126,6 +4550,7 @@ function createAgent(opts) {
       state = { ...state, ...await toolsNode(state) };
       onProgress?.({ stage: "tools", message: "Tools finished" });
       if (state.ctx?.__awaitingApproval) break;
+      if (state.ctx?.__awaitingUserQuestion) break;
       if (checkpointIfRequested("after_tools")) break;
       if (state.ctx?.__finalizedDueToStructuredOutput) break;
       if (reflectNode && resolvedReasoning?.reflection.enabled) {
@@ -4150,7 +4575,7 @@ function createAgent(opts) {
     if (soManager && !state.ctx?.__finalizedDueToStructuredOutput) {
       const lastForParse = state.messages[state.messages.length - 1];
       if (lastForParse?.role === "assistant") {
-        const assistantText = extractMessageText2(lastForParse);
+        const assistantText = extractMessageText(lastForParse);
         if (assistantText) {
           const parsed = soManager.parseFromContent(assistantText);
           if (parsed.success) {
@@ -4196,7 +4621,7 @@ function createAgent(opts) {
     }
     const lastAfterLoop = state.messages[state.messages.length - 1];
     if (lastAfterLoop?.role === "tool" && !pausedStage) {
-      const isExpectedExit = state.ctx?.__awaitingApproval || state.ctx?.__cancelled || state.ctx?.__finalizedDueToStructuredOutput || state.ctx?.__finalizedDueToToolLimit || state.ctx?.__needsSummarization || state.ctx?.__limitBreached;
+      const isExpectedExit = state.ctx?.__awaitingApproval || state.ctx?.__awaitingUserQuestion || state.ctx?.__cancelled || state.ctx?.__finalizedDueToStructuredOutput || state.ctx?.__finalizedDueToToolLimit || state.ctx?.__needsSummarization || state.ctx?.__limitBreached;
       if (!isExpectedExit) {
         throw new Error(
           "Agent loop terminated with a pending tool response but no subsequent model invocation. This usually indicates a model provider error or exhausted iteration budget."
@@ -4214,7 +4639,17 @@ function createAgent(opts) {
       const { setTokenCounter: setTokenCounter2 } = await Promise.resolve().then(() => (init_utilTokens(), utilTokens_exports));
       setTokenCounter2(userTokenCounter);
     }
-    const onEvent = config?.onEvent;
+    const callerOnEvent = config?.onEvent;
+    const onEvent = askUserOnQuestion ? (event) => {
+      if (event && event.type === "user_question") {
+        try {
+          askUserOnQuestion(event);
+        } catch (err) {
+          console.warn("[agent-sdk] humanInTheLoop.askUser.onQuestion error:", err);
+        }
+      }
+      callerOnEvent?.(event);
+    } : callerOnEvent;
     const onProgress = config?.onProgress;
     const onStream = config?.onStream;
     const streamEnabled = config?.stream === true;
@@ -4258,6 +4693,7 @@ function createAgent(opts) {
       metadata: input.metadata,
       ctx,
       pendingApprovals: input.pendingApprovals || [],
+      pendingUserQuestions: input.pendingUserQuestions || [],
       agent: input.agent || runtimeWithInvokeLimits,
       usage: input.usage || { perRequest: [], totals: {} }
     };
@@ -4292,7 +4728,7 @@ function createAgent(opts) {
     const isTransientSummarizationExit = !!res.ctx?.__needsSummarization;
     const finalAssistantMsg = isTransientSummarizationExit ? void 0 : getLastAssistantMessage(res.messages);
     const finalIsSyntheticSummary = !isTransientSummarizationExit && finalAssistantMsg && isSyntheticSummaryMessage(finalAssistantMsg);
-    const content = isTransientSummarizationExit || finalIsSyntheticSummary ? "" : extractMessageText2(finalAssistantMsg);
+    const content = isTransientSummarizationExit || finalIsSyntheticSummary ? "" : extractMessageText(finalAssistantMsg);
     let parsed = void 0;
     let outputError = void 0;
     if (soManager) {
@@ -4334,11 +4770,13 @@ function createAgent(opts) {
     return invokeAgent(restoredState, config);
   };
   const resolveToolApproval = (state, resolution) => resolveToolApprovalState(state, resolution);
+  const resolveUserQuestion = (state, resolution) => resolveUserQuestionState(state, resolution);
   const instance = {
     invoke: invokeAgent,
     snapshot: snapshotState,
     resume: resumeAgent,
     resolveToolApproval,
+    resolveUserQuestion,
     asTool: ({ toolName, description, inputDescription }) => {
       const schema = zod.z.object({ input: zod.z.string().describe(inputDescription || "Input for delegated agent") });
       const delegatedTool = createTool({
@@ -4598,7 +5036,7 @@ function renderMemoryBlock(facts) {
 function clampToBudget(messages, maxContextTokens) {
   let working = [...messages];
   while (working.length > 2) {
-    const tokenCount = countApproxTokens(working.map(extractMessageText2).join("\n"));
+    const tokenCount = countApproxTokens(working.map(extractMessageText).join("\n"));
     if (tokenCount <= maxContextTokens) return working;
     const firstNonSystem = working.findIndex((message, index) => !(index === 0 && message.role === "system"));
     if (firstNonSystem < 0) break;
@@ -5655,7 +6093,20 @@ function createSmartAgent(opts) {
   const userTools = opts.tools ?? [];
   const factoryStateRef = { toolHistory: void 0, toolHistoryArchived: void 0, todoList: void 0, planVersion: 0, adherenceScore: 0 };
   const factoryContextTools = createContextTools(factoryStateRef, { planningEnabled, includeGetToolResponse: false });
+  const askUserConfig = (() => {
+    const raw = opts.humanInTheLoop?.askUser;
+    if (!raw) return void 0;
+    if (raw === true) return { enabled: true, allowFreeText: true };
+    return {
+      enabled: true,
+      allowFreeText: raw.allowFreeText !== false,
+      promptOverride: raw.promptOverride
+    };
+  })();
   const factoryToolsWithoutRecovery = [...userTools, ...factoryContextTools];
+  if (askUserConfig) {
+    factoryToolsWithoutRecovery.push(createAskUserQuestionTool(factoryStateRef, askUserConfig));
+  }
   const soManagerFactory = opts.outputSchema ? new StructuredOutputManager(opts.outputSchema, resolveStrategy(opts.model)) : void 0;
   const modelCapabilities = opts.outputSchema ? getModelCapabilities(opts.model) : void 0;
   const responseFinalizeTool = soManagerFactory && modelCapabilities?.structuredOutput !== "native" ? soManagerFactory.getResponseTool() : void 0;
@@ -5665,6 +6116,7 @@ function createSmartAgent(opts) {
     const recoveryTool = createGetToolResponseTool(ref);
     const base2 = [...userTools, ...ctxTools];
     if (responseFinalizeTool) base2.push(responseFinalizeTool);
+    if (askUserConfig) base2.push(createAskUserQuestionTool(ref, askUserConfig));
     const without = base2;
     const withRec = [...without, recoveryTool];
     return { stateRef: ref, toolsWithoutRecovery: without, toolsWithRecovery: withRec };
@@ -5687,7 +6139,7 @@ function createSmartAgent(opts) {
   ].join("\n");
   function latestUserPrompt(messages) {
     const latest = [...messages].reverse().find((message) => message.role === "user");
-    return latest ? extractMessageText2(latest) : "";
+    return latest ? extractMessageText(latest) : "";
   }
   async function syncMemory(state) {
     const query = latestUserPrompt(state.messages || []);
@@ -5849,6 +6301,7 @@ function createSmartAgent(opts) {
     snapshot: base.snapshot,
     resume: base.resume,
     resolveToolApproval: base.resolveToolApproval,
+    resolveUserQuestion: base.resolveUserQuestion,
     asTool: base.asTool,
     asHandoff: base.asHandoff,
     __runtime: base.__runtime
@@ -8174,6 +8627,7 @@ exports.countApproxTokens = countApproxTokens;
 exports.countMessagesTokens = countMessagesTokens;
 exports.createAgent = createAgent;
 exports.createAgentNode = createAgentNode;
+exports.createAskUserQuestionTool = createAskUserQuestionTool;
 exports.createCodeGuardrail = createCodeGuardrail;
 exports.createContextSummarizeNode = createContextSummarizeNode;
 exports.createContextTools = createContextTools;
@@ -8215,6 +8669,7 @@ exports.regexRule = regexRule;
 exports.resolveMemoryStore = resolveMemoryStore;
 exports.resolveStrategy = resolveStrategy;
 exports.resolveToolApprovalState = resolveToolApprovalState;
+exports.resolveUserQuestionState = resolveUserQuestionState;
 exports.restoreSnapshot = restoreSnapshot;
 exports.runSmartAgentEvalHarness = runSmartAgentEvalHarness;
 exports.setTokenCounter = setTokenCounter;