@cognipeer/agent-sdk 0.6.5 → 0.6.6

package/README.md

@@ -37,7 +37,8 @@ Highlights:
 - **Unified reasoning surface** – one `reasoning` config controls provider-native reasoning and post-tool plain-text reflections.
 - **Structured output** – provide a Zod schema and the agent injects a finalize tool to capture JSON deterministically.
 - **Multi-agent and handoffs** – wrap agents as tools or transfer control mid-run with `asTool` / `asHandoff`.
-- **Usage + events** – normalize provider usage, surface `tool_call`, `plan`, `summarization`, `reflection`, `metadata`, and `handoff` events.
+- **Human-in-the-loop** – `needsApproval` tools pause for review; `humanInTheLoop.askUser` enables a built-in `ask_user_question` tool that pauses with a structured multi-choice prompt and resumes from the user's answer.
+- **Usage + events** – normalize provider usage, surface `tool_call`, `tool_approval`, `user_question`, `plan`, `summarization`, `reflection`, `metadata`, and `handoff` events.
 - **Structured tracing** – optional per-invoke JSON traces with metadata, payload capture, and pluggable sinks (file, HTTP, Cognipeer, custom).
 
 ## What’s inside
@@ -267,6 +268,7 @@ console.log(res.content);
 - **Planning discipline** – when planning is enabled the system prompt distinguishes full plan writes from incremental plan updates and emits `plan` events as todos change.
 - **Structured output** – supply `outputSchema` and the framework adds a hidden `response` finalize tool; parsed JSON is returned as `result.output`.
 - **Multi-agent orchestration** – reuse agents via `agent.asTool({ toolName })` or perform handoffs that swap runtimes mid-execution.
+- **Ask the user** – opt in with `humanInTheLoop: { askUser: true }` to give the model an `ask_user_question` tool that pauses the run; resume by calling `agent.resolveUserQuestion(state, { id, answers })`. The global `allowFreeText` flag controls whether "Other" / typed answers are allowed.
 - **MCP + LangChain tools** – any object satisfying the minimal tool interface works; LangChain’s `Tool` implementations plug in directly.
 - **Vision input** – message parts accept base64 or URL images for multimodal requests.
 - **Observability hooks** – `config.onEvent` surfaces tool lifecycle, summarization, reflection, metadata, and final answer events for streaming UIs or CLIs.
@@ -285,6 +287,7 @@ Examples live under `examples/` with per-folder READMEs. Build the package first
 | `summarize-context/` | Summaries + `get_tool_response` raw retrieval. |
 | `structured-output/` | Zod schema finalize tool and parsed outputs. |
 | `rewrite-summary/` | Continue conversations after summaries are injected. |
+| `ask-user/` | Built-in `ask_user_question` tool, structured multi-choice prompt, resume with user's answer. |
 | `multi-agent/` | Delegating between agents via `asTool`. |
 | `handoff/` | Explicit runtime handoffs. |
 | `mcp-tavily/` | MCP remote tool discovery. |
@@ -349,7 +352,9 @@ Exported helpers (`agent-sdk/src/index.ts`):
 **Utilities:**
 - `buildSystemPrompt(extra?, planning?, name?)`
 - `setTokenCounter`, `getTokenCounter`, `defaultTokenCounter` – swap in a real tokenizer (tiktoken, etc.) globally or per-invoke
-- Node factories (`nodes/*`), context helpers, token utilities, and full TypeScript types (`SmartAgentOptions`, `SmartState`, `AgentInvokeResult`, etc.).
+- `resolveToolApprovalState`, `resolveUserQuestionState` – pure helpers behind `agent.resolveToolApproval` / `agent.resolveUserQuestion` for callers that want to apply a resolution outside the agent factory.
+- `createAskUserQuestionTool(stateRef, { allowFreeText, promptOverride })` – exposed for advanced users that want to attach the human-in-the-loop tool manually instead of via `humanInTheLoop.askUser`.
+- Node factories (`nodes/*`), context helpers, token utilities, and full TypeScript types (`SmartAgentOptions`, `SmartState`, `AgentInvokeResult`, `PendingUserQuestion`, `UserQuestionResolution`, etc.).
 
 `SmartAgentOptions` accepts the usual suspects (`model`, `tools`, `limits`, `runtimeProfile`, `customProfile`, `useTodoList`, `summarization`, `reasoning`, `usageConverter`, `tracing`, `tokenCounter`, `costEstimator`). See `docs/api/` for detailed type references.
 

package/dist/index.cjs

@@ -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
     };
@@ -2594,13 +2595,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;
@@ -2674,6 +2678,7 @@ function createToolsNode(initialTools, opts) {
       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;
@@ -2885,6 +2890,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;
@@ -3022,15 +3043,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 +3063,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 +3074,10 @@ function createToolsNode(initialTools, opts) {
                 awaitingApproval = true;
                 return;
               }
+              if (result.status === "awaiting_user_question") {
+                awaitingUserQuestion = true;
+                return;
+              }
             } catch (err) {
               workerError.err = err;
               return;
@@ -3111,11 +3140,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 +3611,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 +4042,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 +4101,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) {
@@ -4126,6 +4392,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) {
@@ -4196,7 +4463,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 +4481,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 +4535,7 @@ function createAgent(opts) {
       metadata: input.metadata,
       ctx,
       pendingApprovals: input.pendingApprovals || [],
+      pendingUserQuestions: input.pendingUserQuestions || [],
       agent: input.agent || runtimeWithInvokeLimits,
       usage: input.usage || { perRequest: [], totals: {} }
     };
@@ -4334,11 +4612,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({
@@ -5655,7 +5935,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 +5958,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 };
@@ -5849,6 +6143,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 +8469,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 +8511,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;