@librechat/agents 3.4.3 → 3.4.5

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/messages/assistantPhase.test.ts

@@ -0,0 +1,75 @@
+import {
+  getAssistantTextPhase,
+  getMessageCreationContentMetadata,
+  splitAssistantTextContentByPhase,
+} from './assistantPhase';
+import { ContentTypes } from '@/common';
+
+describe('assistant phase metadata', () => {
+  it('reads provider-native Open Responses phase metadata', () => {
+    const part = {
+      type: ContentTypes.TEXT,
+      text: '',
+      phase: 'commentary' as const,
+    };
+
+    expect(getAssistantTextPhase(part)).toBe('commentary');
+    expect(getMessageCreationContentMetadata([part])).toEqual({
+      content_type: ContentTypes.TEXT,
+      phase: 'commentary',
+    });
+  });
+
+  it('reads LangChain standard-content extras', () => {
+    const part = {
+      type: ContentTypes.TEXT,
+      text: '',
+      extras: { phase: 'final_answer' as const },
+    };
+
+    expect(getMessageCreationContentMetadata([part])).toEqual({
+      content_type: ContentTypes.TEXT,
+      phase: 'final_answer',
+    });
+  });
+
+  it('announces reasoning without inventing a text phase', () => {
+    expect(
+      getMessageCreationContentMetadata([
+        { type: ContentTypes.THINK, think: 'checking' },
+      ])
+    ).toEqual({ content_type: ContentTypes.THINK });
+  });
+
+  it('preserves every provider phase in a multi-block text chunk', () => {
+    const commentary = {
+      type: ContentTypes.TEXT,
+      text: 'I will inspect the session path.',
+      phase: 'commentary' as const,
+    };
+    const moreCommentary = {
+      type: ContentTypes.TEXT,
+      text: 'The refresh branch is stale.',
+      phase: 'commentary' as const,
+    };
+    const finalAnswer = {
+      type: ContentTypes.TEXT,
+      text: 'The refresh path is fixed.',
+      phase: 'final_answer' as const,
+    };
+
+    const groups = splitAssistantTextContentByPhase([
+      commentary,
+      moreCommentary,
+      finalAnswer,
+    ]);
+
+    expect(groups).toEqual([[commentary, moreCommentary], [finalAnswer]]);
+    expect(
+      groups.map((group) => getMessageCreationContentMetadata(group))
+    ).toEqual([
+      { content_type: ContentTypes.TEXT, phase: 'commentary' },
+      { content_type: ContentTypes.TEXT, phase: 'final_answer' },
+    ]);
+  });
+});

package/src/messages/assistantPhase.ts

@@ -0,0 +1,91 @@
+import type { AssistantTextPhase } from '@/types/assistantPhase';
+import type { MessageContentComplex } from '@/types/stream';
+import { ContentTypes } from '@/common';
+
+export type MessageCreationContentMetadata = {
+  content_type?: ContentTypes.TEXT | ContentTypes.THINK;
+  phase?: AssistantTextPhase;
+};
+
+function toAssistantTextPhase(value: unknown): AssistantTextPhase | undefined {
+  return value === 'commentary' || value === 'final_answer' ? value : undefined;
+}
+
+/** Reads both provider-native and LangChain standard-content phase fields. */
+export function getAssistantTextPhase(
+  contentPart: MessageContentComplex
+): AssistantTextPhase | undefined {
+  return (
+    toAssistantTextPhase(contentPart.phase) ??
+    toAssistantTextPhase(contentPart.extras?.phase)
+  );
+}
+
+/**
+ * Keeps provider-authored text phases in distinct message-creation steps.
+ * Open Responses may return commentary and final-answer blocks in one chunk;
+ * collapsing the array into one step would assign the first block's phase to
+ * every block and hide the boundary that closes an activity phase.
+ */
+export function splitAssistantTextContentByPhase(
+  content: MessageContentComplex[]
+): MessageContentComplex[][] {
+  const groups: MessageContentComplex[][] = [];
+  for (const contentPart of content) {
+    const phase = getAssistantTextPhase(contentPart);
+    const currentGroup = groups.at(-1);
+    if (
+      currentGroup == null ||
+      getAssistantTextPhase(currentGroup[0]) !== phase
+    ) {
+      groups.push([contentPart]);
+      continue;
+    }
+    currentGroup.push(contentPart);
+  }
+  return groups;
+}
+
+function isTextPart(contentPart: MessageContentComplex): boolean {
+  return contentPart.type?.startsWith(ContentTypes.TEXT) ?? false;
+}
+
+function isReasoningPart(contentPart: MessageContentComplex): boolean {
+  return (
+    contentPart.type === ContentTypes.THINK ||
+    (contentPart.type?.startsWith(ContentTypes.THINKING) ?? false) ||
+    (contentPart.type?.startsWith(ContentTypes.REASONING) ?? false) ||
+    (contentPart.type?.startsWith(ContentTypes.REASONING_CONTENT) ?? false) ||
+    contentPart.type === 'redacted_thinking'
+  );
+}
+
+/**
+ * Derives additive message-creation metadata before a content delta is
+ * dispatched. The fallback covers string-only providers whose semantic lane
+ * is tracked by the stream handler rather than represented on a block.
+ */
+export function getMessageCreationContentMetadata(
+  content: string | MessageContentComplex[] | undefined,
+  fallbackContentType?: ContentTypes.TEXT | ContentTypes.THINK
+): MessageCreationContentMetadata {
+  if (!Array.isArray(content)) {
+    return fallbackContentType == null
+      ? {}
+      : { content_type: fallbackContentType };
+  }
+  const textPart = content.find(isTextPart);
+  if (textPart != null) {
+    const phase = getAssistantTextPhase(textPart);
+    return {
+      content_type: ContentTypes.TEXT,
+      ...(phase == null ? {} : { phase }),
+    };
+  }
+  if (content.some(isReasoningPart)) {
+    return { content_type: ContentTypes.THINK };
+  }
+  return fallbackContentType == null
+    ? {}
+    : { content_type: fallbackContentType };
+}

package/src/messages/index.ts

@@ -14,3 +14,4 @@ export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';
 export * from './recency';
+export * from './assistantPhase';

package/src/prompts/activityLabel.ts

@@ -1,5 +1,8 @@
+import type {
+  ActivityLabelToolEntry,
+  ActivityPhaseEntry,
+} from '@/types/activityLabel';
 import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
-import type { ActivityLabelToolEntry } from '@/types/activityLabel';
 import { shouldRedactTool } from '@/langfuseToolOutputTracing';
 
 /**
@@ -25,6 +28,29 @@ Examples:
 - Read project config and dependency manifests
 - Attempted database migration, hit permission errors`;
 
+/** Default system prompt for a run-wide parent activity phase. */
+export const ACTIVITY_PHASE_LABEL_PROMPT = `Summarize what this phase of an agent run accomplished. The result appears as the header of one collapsed parent group containing several activities.
+
+Rules:
+- One line, 8 to 18 words, past tense
+- Lead with the concrete outcome and name the most distinctive subject
+- Synthesize the phase; do not enumerate, count, or restate individual activities
+- Describe failures plainly when they are the phase's material outcome
+- Never mention tool names, calls, arguments, reasoning, commentary, or activity counts
+- Output only the summary — no quotes, no trailing punctuation, no preamble
+
+Examples:
+- Reconciled authentication behavior and fixed the failing session refresh path
+- Compared deployment options and documented the safest production rollout
+- Investigated database latency but could not confirm the suspected index regression
+
+Bad examples:
+- Used three tools to inspect files and run tests
+- Searched code, read configuration, and updated middleware`;
+
+/** Hard ceiling across every activity/context section in one phase request. */
+export const ACTIVITY_PHASE_PROMPT_MAX_LENGTH = 12_000;
+
 /** Truncates a serialized value for the label prompt. */
 export function truncateForLabel(value: string, maxLength: number): string {
   if (value.length <= maxLength) {
@@ -105,6 +131,10 @@ const PREVIOUS_LABEL_LIMIT = 200;
  *  produce one, and the cap keeps a 200-call programmatic batch from
  *  building an enormous prompt out of per-field-bounded pieces. */
 const MAX_PROMPT_ENTRIES = 12;
+const MAX_PHASE_ACTIVITIES = 12;
+const MAX_PHASE_CONTEXT = 3;
+const MAX_PHASE_TOOL_ENTRIES = 6;
+export const ACTIVITY_PHASE_LABEL_MAX_LENGTH = 160;
 
 export type BuildActivityLabelPromptParams = {
   entries: ActivityLabelToolEntry[];
@@ -240,3 +270,149 @@ export function buildActivityLabelPrompt({
   sections.push('Header:');
   return sections.join('\n\n');
 }
+
+export type BuildActivityPhaseLabelPromptParams = {
+  activities: ActivityPhaseEntry[];
+  totalActivityCount?: number;
+  charLimit: number;
+  assistantContext?: string[];
+  redaction?: ResolvedLangfuseToolOutputTracingConfig;
+};
+
+/**
+ * Builds bounded, redaction-aware evidence for a parent activity phase.
+ * Committed child labels are preferred; raw tool/reasoning evidence is only
+ * used when no child label exists.
+ */
+export function buildActivityPhaseLabelPrompt({
+  activities,
+  totalActivityCount,
+  charLimit,
+  assistantContext,
+  redaction,
+}: BuildActivityPhaseLabelPromptParams): string {
+  const freeFormSuppressed =
+    redaction != null &&
+    (redaction.enabled === false || redaction.redactedToolNames.size > 0);
+  const sections: string[] = [];
+  if (
+    !freeFormSuppressed &&
+    assistantContext != null &&
+    assistantContext.length > 0
+  ) {
+    const context = assistantContext
+      .slice(-MAX_PHASE_CONTEXT)
+      .map((text) =>
+        truncateForLabel(text.replace(/\s+/g, ' ').trim(), charLimit)
+      )
+      .filter((text) => text.length > 0);
+    if (context.length > 0) {
+      sections.push(
+        'Intermediate assistant context (do not quote or restate):\n' +
+          context.map((text) => `- ${text}`).join('\n')
+      );
+    }
+  }
+
+  let hasDescribableEvidence = false;
+  const activityLines = activities
+    .slice(0, MAX_PHASE_ACTIVITIES)
+    .map((activity, index) => {
+      let status = 'completed';
+      if (activity.status === 'error') {
+        status = 'failed';
+      } else if (activity.status === 'partial') {
+        status = 'partial';
+      }
+      if (
+        !freeFormSuppressed &&
+        activity.label != null &&
+        activity.label.trim() !== ''
+      ) {
+        hasDescribableEvidence = true;
+        return `${index + 1}. ${status}: ${truncateForLabel(activity.label.replace(/\s+/g, ' ').trim(), charLimit)}`;
+      }
+
+      const evidence: string[] = [];
+      if (
+        !freeFormSuppressed &&
+        activity.thinkingExcerpts != null &&
+        activity.thinkingExcerpts.length > 0
+      ) {
+        evidence.push(
+          ...activity.thinkingExcerpts
+            .slice(0, MAX_THINKING_EXCERPTS)
+            .map((excerpt) =>
+              truncateForLabel(excerpt.replace(/\s+/g, ' ').trim(), charLimit)
+            )
+            .filter((excerpt) => excerpt.length > 0)
+            .map((excerpt) => `context=${excerpt}`)
+        );
+      }
+      if (activity.entries != null && activity.entries.length > 0) {
+        evidence.push(
+          ...activity.entries.slice(0, MAX_PHASE_TOOL_ENTRIES).map((entry) => {
+            const entryRedacted =
+              redaction != null && shouldRedactTool(entry.toolName, redaction);
+            const input = truncateForLabel(
+              serializeForLabel(entry.toolInput, charLimit),
+              charLimit
+            );
+            let outcome: string;
+            if (entryRedacted) {
+              outcome = redaction.redactionText;
+            } else if (entry.status === 'error') {
+              outcome = `ERROR: ${truncateForLabel(
+                entry.error ?? 'unknown error',
+                charLimit
+              )}`;
+            } else {
+              outcome = truncateForLabel(
+                serializeForLabel(entry.toolOutput, charLimit),
+                charLimit
+              );
+            }
+            return `${entry.toolName}(${input}) → ${outcome}`;
+          })
+        );
+      }
+      if (evidence.length > 0) {
+        hasDescribableEvidence = true;
+      }
+      return `${index + 1}. ${status}${evidence.length > 0 ? `: ${evidence.join('; ')}` : ''}`;
+    });
+
+  if (!hasDescribableEvidence) {
+    return '';
+  }
+
+  const activityCount = Math.max(activities.length, totalActivityCount ?? 0);
+  if (activityCount > MAX_PHASE_ACTIVITIES) {
+    activityLines.push(
+      `${MAX_PHASE_ACTIVITIES + 1}. …and ${activityCount - MAX_PHASE_ACTIVITIES} more activities`
+    );
+  }
+  sections.push(
+    'Activities in this phase (synthesize; do not restate):\n' +
+      activityLines.join('\n')
+  );
+  const terminalCue = '\n\nPhase summary:';
+  const evidence = sections.join('\n\n');
+  const prompt = evidence + terminalCue;
+  if (prompt.length <= ACTIVITY_PHASE_PROMPT_MAX_LENGTH) {
+    return prompt;
+  }
+  const evidenceLimit =
+    ACTIVITY_PHASE_PROMPT_MAX_LENGTH - terminalCue.length - 1;
+  return `${evidence.slice(0, evidenceLimit).trimEnd()}…${terminalCue}`;
+}
+
+/** Normalizes a model result for safe single-row persistence and display. */
+export function normalizeActivityPhaseLabel(label: string): string {
+  const normalized = label
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/[.!?]+$/g, '');
+  return truncateForLabel(normalized, ACTIVITY_PHASE_LABEL_MAX_LENGTH);
+}