@librechat/agents 3.4.4 → 3.4.5

package/dist/types/types/hitl.d.ts

@@ -157,15 +157,35 @@ export interface AskUserQuestionRequest {
      */
     multiSelect?: boolean;
 }
+/** One independently answerable question in a batched question request. */
+export interface AskUserQuestionBatchItem extends AskUserQuestionRequest {
+    /** Batch-unique identifier (`[A-Za-z][A-Za-z0-9_-]{0,63}`). */
+    id: string;
+    /** Optional short heading rendered above the question. */
+    header?: string;
+}
+/** Input shape for one tool call that asks one to four questions together. */
+export interface AskUserQuestionsRequest {
+    questions: AskUserQuestionBatchItem[];
+}
 /**
  * Structured payload the SDK passes to `interrupt()` when an agent (or
  * a custom node) needs to ask the user a clarifying question. Mirrors
- * Claude Code's `AskUserQuestion` semantic. Resume value:
- * `AskUserQuestionResolution`.
+ * Claude Code's `AskUserQuestion` semantic. Resume value is
+ * `AskUserQuestionResolution` for a single question, or
+ * `AskUserQuestionsResolution` when `questions` is present.
  */
 export interface AskUserQuestionInterruptPayload {
     type: 'ask_user_question';
+    /**
+     * Single-question request, or the first question as a compatibility
+     * fallback when `questions` contains a batch. This lets existing hosts show
+     * a useful preview during a staged rollout, but they must support `questions`
+     * and `AskUserQuestionsResolution` before enabling a batched tool schema.
+     */
     question: AskUserQuestionRequest;
+    /** One to four questions collected by one `ask_user_question` tool call. */
+    questions?: AskUserQuestionsRequest['questions'];
     /**
      * The `tool_call_id` of the ask-tool call that raised this interrupt,
      * when the tool body supplied it (see `askUserQuestion`'s `options`).
@@ -175,6 +195,10 @@ export interface AskUserQuestionInterruptPayload {
      */
     tool_call_id?: string;
 }
+/** Batch-specialized ask payload for hosts that render several questions. */
+export interface AskUserQuestionsInterruptPayload extends AskUserQuestionInterruptPayload {
+    questions: AskUserQuestionsRequest['questions'];
+}
 /**
  * Discriminated union of every interrupt payload the SDK raises. New
  * variants can be added without breaking existing handlers as long as
@@ -194,6 +218,11 @@ export interface AskUserQuestionResolution {
      */
     answer: string;
 }
+/** Resume value for a batched `ask_user_question` interrupt. */
+export interface AskUserQuestionsResolution {
+    /** Human answers keyed by each `AskUserQuestionBatchItem.id`. */
+    answers: Record<string, string>;
+}
 /**
  * Type guard narrowing an arbitrary value to a `ToolApprovalInterruptPayload`.
  * Accepts `unknown` (not just `HumanInterruptPayload`) because hosts can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.4.4",
+  "version": "3.4.5",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -199,6 +199,7 @@
     "supervised": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/supervised.ts --provider anthropic --name Jo --location \"New York, NY\"",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:live:handoffs": "RUN_HANDOFF_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/agent-handoffs.live.test.ts --runInBand",
+    "test:live:ask-user-questions": "RUN_ASK_USER_QUESTIONS_LIVE_TESTS=1 NODE_OPTIONS='--experimental-vm-modules' jest src/specs/ask-user-questions.live.test.ts --runInBand",
     "test:memory": "NODE_OPTIONS='--expose-gc' npx jest src/specs/title.memory-leak.test.ts",
     "test:all": "npm test -- --testPathIgnorePatterns=title.memory-leak.test.ts && npm run test:memory",
     "reinstall": "npm run clean && npm ci && rm -rf ./dist && npm run build",

package/src/hitl/askUserQuestions.ts

@@ -0,0 +1,126 @@
+import { interrupt } from '@langchain/langgraph';
+import type {
+  AskUserQuestionBatchItem,
+  AskUserQuestionRequest,
+  AskUserQuestionsInterruptPayload,
+  AskUserQuestionsRequest,
+  AskUserQuestionsResolution,
+} from '@/types/hitl';
+import {
+  ASK_USER_QUESTION_ID_PATTERN,
+  isAskUserQuestionRequest,
+  MAX_ASK_USER_QUESTIONS,
+} from './askUserQuestionsInterrupt';
+
+function validateQuestions(
+  questions: readonly AskUserQuestionBatchItem[]
+): AskUserQuestionBatchItem {
+  if (questions.length === 0) {
+    throw new RangeError('askUserQuestions requires at least one question.');
+  }
+  if (questions.length > MAX_ASK_USER_QUESTIONS) {
+    throw new RangeError(
+      `askUserQuestions accepts at most ${MAX_ASK_USER_QUESTIONS} questions.`
+    );
+  }
+
+  const ids = new Set<string>();
+  for (const question of questions) {
+    if (!isAskUserQuestionRequest(question)) {
+      throw new TypeError(
+        'askUserQuestions requires each question and option to have valid string fields.'
+      );
+    }
+    if (!ASK_USER_QUESTION_ID_PATTERN.test(question.id)) {
+      throw new Error(
+        'askUserQuestions requires each question id to match [A-Za-z][A-Za-z0-9_-]{0,63}.'
+      );
+    }
+    if (ids.has(question.id)) {
+      throw new Error(
+        `askUserQuestions requires unique question ids; received "${question.id}" more than once.`
+      );
+    }
+    ids.add(question.id);
+  }
+  return questions[0];
+}
+
+interface AskUserQuestionsResolutionCandidate {
+  answers?: unknown;
+}
+
+function validateResolution(
+  value: unknown,
+  questions: readonly AskUserQuestionBatchItem[]
+): AskUserQuestionsResolution {
+  if (typeof value !== 'object' || value === null) {
+    throw new TypeError('askUserQuestions requires an answers object.');
+  }
+  const answers = (value as AskUserQuestionsResolutionCandidate).answers;
+  if (
+    typeof answers !== 'object' ||
+    answers === null ||
+    Array.isArray(answers)
+  ) {
+    throw new TypeError('askUserQuestions requires an answers object.');
+  }
+
+  const validated: Record<string, string> = {};
+  for (const question of questions) {
+    const descriptor = Object.getOwnPropertyDescriptor(answers, question.id);
+    const answer: unknown = descriptor?.value;
+    if (descriptor == null || typeof answer !== 'string') {
+      throw new TypeError(
+        `askUserQuestions requires a string answer for question id "${question.id}".`
+      );
+    }
+    validated[question.id] = answer;
+  }
+  return { answers: validated };
+}
+
+/**
+ * Suspend once to collect answers to several related questions. The first
+ * question is also included in the legacy `question` field so existing hosts
+ * can render a useful fallback during a staged rollout.
+ *
+ * Question ids must be non-empty and unique within the batch. The helper
+ * accepts at most four questions so hosts can render the interaction as one
+ * focused decision surface rather than an unbounded form.
+ *
+ * @example
+ * ```ts
+ * const { answers } = askUserQuestions({
+ *   questions: [
+ *     { id: 'environment', question: 'Which environment?' },
+ *     { id: 'region', question: 'Which region?' },
+ *   ],
+ * });
+ * return `Deploy to ${answers.environment} in ${answers.region}`;
+ * ```
+ */
+export function askUserQuestions(
+  request: AskUserQuestionsRequest,
+  options?: { toolCallId?: string }
+): AskUserQuestionsResolution {
+  const first = validateQuestions(request.questions);
+  const fallback: AskUserQuestionRequest = {
+    question: first.question,
+    ...(first.description != null && { description: first.description }),
+    ...(first.options != null && { options: first.options }),
+    ...(first.multiSelect != null && { multiSelect: first.multiSelect }),
+  };
+  const payload: AskUserQuestionsInterruptPayload = {
+    type: 'ask_user_question',
+    question: fallback,
+    questions: request.questions,
+    ...(options?.toolCallId != null &&
+      options.toolCallId !== '' && { tool_call_id: options.toolCallId }),
+  };
+
+  const resolution = interrupt<AskUserQuestionsInterruptPayload, unknown>(
+    payload
+  );
+  return validateResolution(resolution, request.questions);
+}

package/src/hitl/askUserQuestionsInterrupt.ts

@@ -0,0 +1,115 @@
+import type {
+  AskUserQuestionBatchItem,
+  AskUserQuestionOption,
+  AskUserQuestionRequest,
+  AskUserQuestionsInterruptPayload,
+} from '@/types/hitl';
+import { isAskUserQuestionInterrupt } from '@/types/hitl';
+
+/** Maximum questions supported by one batched clarification interaction. */
+export const MAX_ASK_USER_QUESTIONS = 4;
+
+/** Safe identifier format for answer-map keys in a batched question. */
+export const ASK_USER_QUESTION_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+interface AskUserQuestionOptionCandidate {
+  label?: unknown;
+  value?: unknown;
+}
+
+interface AskUserQuestionCandidate {
+  question?: unknown;
+  description?: unknown;
+  options?: unknown;
+  multiSelect?: unknown;
+}
+
+interface AskUserQuestionBatchItemCandidate extends AskUserQuestionCandidate {
+  id?: unknown;
+  header?: unknown;
+}
+
+function isAskUserQuestionOption(
+  value: unknown
+): value is AskUserQuestionOption {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const option = value as AskUserQuestionOptionCandidate;
+  return typeof option.label === 'string' && typeof option.value === 'string';
+}
+
+function isAskUserQuestionOptions(
+  value: unknown
+): value is AskUserQuestionOption[] {
+  if (!Array.isArray(value)) {
+    return false;
+  }
+  for (let index = 0; index < value.length; index++) {
+    if (!Object.hasOwn(value, index) || !isAskUserQuestionOption(value[index])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function isAskUserQuestionRequest(
+  value: unknown
+): value is AskUserQuestionRequest {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const question = value as AskUserQuestionCandidate;
+  return (
+    typeof question.question === 'string' &&
+    (question.description === undefined ||
+      typeof question.description === 'string') &&
+    (question.options === undefined ||
+      isAskUserQuestionOptions(question.options)) &&
+    (question.multiSelect === undefined ||
+      typeof question.multiSelect === 'boolean')
+  );
+}
+
+function isAskUserQuestionBatchItem(
+  value: unknown
+): value is AskUserQuestionBatchItem {
+  if (!isAskUserQuestionRequest(value)) {
+    return false;
+  }
+  const question = value as AskUserQuestionBatchItemCandidate;
+  return (
+    typeof question.id === 'string' &&
+    ASK_USER_QUESTION_ID_PATTERN.test(question.id) &&
+    (question.header === undefined || typeof question.header === 'string')
+  );
+}
+
+/**
+ * Type guard for the batched form of an `ask_user_question` interrupt. Hosts
+ * use this to select the multi-question UI and `AskUserQuestionsResolution`.
+ */
+export function isAskUserQuestionsInterrupt(
+  payload: unknown
+): payload is AskUserQuestionsInterruptPayload {
+  if (
+    !isAskUserQuestionInterrupt(payload) ||
+    !isAskUserQuestionRequest(payload.question) ||
+    (payload.tool_call_id !== undefined &&
+      typeof payload.tool_call_id !== 'string') ||
+    !Array.isArray(payload.questions) ||
+    payload.questions.length === 0 ||
+    payload.questions.length > MAX_ASK_USER_QUESTIONS
+  ) {
+    return false;
+  }
+
+  const ids = new Set<string>();
+  for (const question of payload.questions) {
+    if (!isAskUserQuestionBatchItem(question) || ids.has(question.id)) {
+      return false;
+    }
+    ids.add(question.id);
+  }
+  return true;
+}

package/src/hitl/index.ts

@@ -5,3 +5,9 @@
  */
 
 export { askUserQuestion } from './askUserQuestion';
+export { askUserQuestions } from './askUserQuestions';
+export {
+  ASK_USER_QUESTION_ID_PATTERN,
+  isAskUserQuestionsInterrupt,
+  MAX_ASK_USER_QUESTIONS,
+} from './askUserQuestionsInterrupt';

package/src/specs/ask-user-questions.live.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Live proof that Anthropic can produce one tool call containing several
+ * questions, pause once, and continue from one keyed batch resolution.
+ *
+ * Run with:
+ * RUN_ASK_USER_QUESTIONS_LIVE_TESTS=1 ANTHROPIC_API_KEY=... npm test -- ask-user-questions.live.test.ts --runInBand
+ */
+import { config as dotenvConfig } from 'dotenv';
+dotenvConfig(
+  process.env.DOTENV_CONFIG_PATH != null
+    ? { path: process.env.DOTENV_CONFIG_PATH }
+    : undefined
+);
+
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import { MemorySaver } from '@langchain/langgraph';
+import { describe, expect, it, jest } from '@jest/globals';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { askUserQuestions } from '@/hitl';
+import { Run } from '@/run';
+
+const shouldRunLive =
+  process.env.RUN_ASK_USER_QUESTIONS_LIVE_TESTS === '1' &&
+  process.env.ANTHROPIC_API_KEY != null &&
+  process.env.ANTHROPIC_API_KEY !== '';
+const describeIfLive = shouldRunLive ? describe : describe.skip;
+const modelName =
+  process.env.ANTHROPIC_BATCH_QUESTIONS_LIVE_MODEL ?? 'claude-sonnet-5';
+
+const questionSchema = z.object({
+  id: z.enum(['metric', 'window']),
+  header: z.string().max(20),
+  question: z.string(),
+  options: z
+    .array(z.object({ label: z.string().max(120), value: z.string() }))
+    .min(2)
+    .max(3),
+  multiSelect: z.boolean(),
+});
+const askUserQuestionsSchema = z.object({
+  questions: z.array(questionSchema).length(2),
+});
+type AskUserQuestionsInput = z.infer<typeof askUserQuestionsSchema>;
+
+const askTool = tool(
+  async (input: AskUserQuestionsInput, config) => {
+    const resolution = askUserQuestions(input, {
+      toolCallId: config.toolCall?.id,
+    });
+    return JSON.stringify(resolution);
+  },
+  {
+    name: 'ask_user_question',
+    description:
+      'Ask the user one to four related questions in one interaction. Put every question in this single tool call.',
+    schema: askUserQuestionsSchema,
+  }
+);
+
+type LiveStreamConfig = Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  streamMode: string;
+};
+
+function streamConfig(threadId: string): LiveStreamConfig {
+  return {
+    configurable: { thread_id: threadId },
+    streamMode: 'values',
+    version: 'v2',
+  };
+}
+
+function messageText(message: BaseMessage): string {
+  if (typeof message.content === 'string') {
+    return message.content;
+  }
+  if (!Array.isArray(message.content)) {
+    return '';
+  }
+  return message.content
+    .map((part) =>
+      typeof part === 'object' &&
+      'text' in part &&
+      typeof part.text === 'string'
+        ? part.text
+        : ''
+    )
+    .join('');
+}
+
+describeIfLive('askUserQuestions live Anthropic integration', () => {
+  jest.setTimeout(120_000);
+
+  it('uses one batched call and continues after one composite answer', async () => {
+    const nonce = `batch-questions-${Date.now()}`;
+    const saver = new MemorySaver();
+    const run = await Run.create<t.IState>({
+      runId: `${nonce}-run`,
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'clarifier',
+            provider: Providers.ANTHROPIC,
+            clientOptions: {
+              modelName,
+              apiKey: process.env.ANTHROPIC_API_KEY,
+              maxTokens: 512,
+              streaming: true,
+            },
+            instructions: `You are testing a batched clarification tool.
+On the first turn, call ask_user_question exactly once. In that one call, ask exactly two questions:
+- id "metric": whether to analyze "workload" or "website"
+- id "window": whether to analyze "24h" or "7d"
+Do not emit two tool calls and do not answer in prose before the tool result.
+After the tool returns, reply exactly: LIVE_BATCH_OK metric=<metric>; window=<window>`,
+            maxContextTokens: 8000,
+            graphTools: [askTool],
+          },
+        ],
+        compileOptions: { checkpointer: saver },
+      },
+      returnContent: true,
+      skipCleanup: true,
+      interruptingToolNames: ['ask_user_question'],
+    });
+    const config = streamConfig(`${nonce}-thread`);
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'Clarify both dimensions before doing any analysis.'
+          ),
+        ],
+      },
+      config
+    );
+
+    const pending = run.getInterrupt();
+    expect(pending?.payload.type).toBe('ask_user_question');
+    if (pending?.payload.type !== 'ask_user_question') {
+      throw new Error('expected ask_user_question interrupt');
+    }
+    expect(pending.payload.questions).toHaveLength(2);
+    expect(pending.payload.questions?.map(({ id }) => id)).toEqual([
+      'metric',
+      'window',
+    ]);
+
+    await run.resume<t.AskUserQuestionsResolution>(
+      { answers: { metric: 'workload', window: '7d' } },
+      config
+    );
+
+    expect(run.getInterrupt()).toBeUndefined();
+    const messages = run.getRunMessages() ?? [];
+    const askCalls = messages.flatMap((message) => {
+      if (message.getType() !== 'ai') {
+        return [];
+      }
+      return ((message as AIMessage).tool_calls ?? []).filter(
+        ({ name }) => name === 'ask_user_question'
+      );
+    });
+    expect(askCalls).toHaveLength(1);
+    expect(askCalls[0].args).toMatchObject({
+      questions: expect.arrayContaining([
+        expect.objectContaining({ id: 'metric' }),
+        expect.objectContaining({ id: 'window' }),
+      ]),
+    });
+
+    const finalText = messages
+      .filter((message) => message.getType() === 'ai')
+      .map(messageText)
+      .join('\n');
+    expect(finalText).toContain('LIVE_BATCH_OK metric=workload; window=7d');
+  });
+});