@librechat/agents 3.4.4 → 3.4.6

package/src/tools/subagent/SubagentExecutor.ts

@@ -45,6 +45,7 @@ import type {
   ReasoningDeltaEvent,
   RunStep,
   RunStepDeltaEvent,
+  RunStepClosedEvent,
   StandardGraphInput,
   ExecutableSubagentConfigEntry,
   ResolvedSubagentConfig,
@@ -156,8 +157,7 @@ function cloneToolSessionContext(
       : {
         files: context.files.map((file) => ({
           ...file,
-          storage_session_id:
-              file.storage_session_id ?? context.session_id,
+          storage_session_id: file.storage_session_id ?? context.session_id,
         })),
       }),
   };
@@ -200,8 +200,7 @@ function seedChildGraphSessions(
         );
       const files = existing.files == null ? [] : [...existing.files];
       for (const file of context.files) {
-        const storageSessionId =
-          file.storage_session_id ?? context.session_id;
+        const storageSessionId = file.storage_session_id ?? context.session_id;
         const key = `${storageSessionId}\0${file.id}`;
         if (seenFiles.has(key)) {
           continue;
@@ -263,10 +262,12 @@ type SanitizedRunStep = Partial<
   Pick<
     RunStep,
     | 'agentId'
+    | 'created_at'
     | 'groupId'
     | 'id'
     | 'index'
     | 'runId'
+    | 'status'
     | 'stepIndex'
     | 'summary'
     | 'type'
@@ -276,6 +277,8 @@ type SanitizedRunStep = Partial<
   stepDetails?: SanitizedStepDetails;
 };
 
+type SanitizedRunStepClosed = Partial<RunStepClosedEvent>;
+
 type SanitizedStepDetails =
   | {
       type: StepTypes.MESSAGE_CREATION;
@@ -313,6 +316,7 @@ type SanitizedStepCompleted =
       index?: number;
       type: 'tool_call';
       tool_call?: SanitizedProcessedToolCall;
+      completed_at?: number;
     }
   | {
       type: 'summary';
@@ -2825,6 +2829,10 @@ export class SubagentExecutor {
           scheduleWrap(eventName, 'run_step_completed', data, memberAgentId);
           return;
         }
+        if (eventName === GraphEvents.ON_RUN_STEP_CLOSED) {
+          scheduleWrap(eventName, 'run_step_closed', data, memberAgentId);
+          return;
+        }
         if (eventName === GraphEvents.ON_MESSAGE_DELTA) {
           scheduleWrap(eventName, 'message_delta', data, memberAgentId);
           return;
@@ -3179,6 +3187,9 @@ export function sanitizeForwardedSubagentUpdateData(
   if (eventName === GraphEvents.ON_RUN_STEP_COMPLETED) {
     return sanitizeRunStepCompletedUpdateData(data);
   }
+  if (eventName === GraphEvents.ON_RUN_STEP_CLOSED) {
+    return sanitizeRunStepClosedUpdateData(data);
+  }
   if (eventName === GraphEvents.ON_MESSAGE_DELTA) {
     return sanitizeMessageDeltaUpdateData(data);
   }
@@ -3230,10 +3241,12 @@ function sanitizeRunStepUpdateData(
   const step = data as Partial<RunStep>;
   const sanitized: SanitizedRunStep = {};
   assignString(sanitized, 'agentId', step.agentId);
+  assignNumber(sanitized, 'created_at', step.created_at);
   assignNumber(sanitized, 'groupId', step.groupId);
   assignString(sanitized, 'id', step.id);
   assignNumber(sanitized, 'index', step.index);
   assignString(sanitized, 'runId', step.runId);
+  assignString(sanitized, 'status', step.status);
   assignNumber(sanitized, 'stepIndex', step.stepIndex);
   assignString(sanitized, 'type', step.type);
   if (step.summary !== undefined) {
@@ -3246,6 +3259,27 @@ function sanitizeRunStepUpdateData(
   return sanitized;
 }
 
+function sanitizeRunStepClosedUpdateData(
+  data: unknown
+): SanitizedRunStepClosed | undefined {
+  if (!isObjectLike(data)) {
+    return undefined;
+  }
+  const event = data as Partial<RunStepClosedEvent>;
+  const sanitized: SanitizedRunStepClosed = {};
+  assignString(sanitized, 'agentId', event.agentId);
+  assignNumber(sanitized, 'closed_at', event.closed_at);
+  assignNumber(sanitized, 'created_at', event.created_at);
+  assignNumber(sanitized, 'groupId', event.groupId);
+  assignString(sanitized, 'id', event.id);
+  assignNumber(sanitized, 'index', event.index);
+  assignString(sanitized, 'runId', event.runId);
+  assignString(sanitized, 'status', event.status);
+  assignNumber(sanitized, 'stepIndex', event.stepIndex);
+  assignString(sanitized, 'type', event.type);
+  return sanitized;
+}
+
 function sanitizeRunStepDeltaUpdateData(
   data: unknown
 ): SanitizedRunStepDelta | undefined {
@@ -3389,6 +3423,7 @@ function sanitizeStepCompleted(
     id?: unknown;
     index?: unknown;
     tool_call?: unknown;
+    completed_at?: unknown;
   };
   if (completed.type === 'summary') {
     return {
@@ -3402,6 +3437,7 @@ function sanitizeStepCompleted(
   const sanitized: SanitizedStepCompleted = { type: 'tool_call' };
   assignString(sanitized, 'id', completed.id);
   assignNumber(sanitized, 'index', completed.index);
+  assignNumber(sanitized, 'completed_at', completed.completed_at);
   sanitized.tool_call = sanitizeProcessedToolCall(completed.tool_call);
   return sanitized;
 }
@@ -3520,6 +3556,12 @@ export function summarizeEvent(eventName: string, data: unknown): string {
     }
     return 'Step complete';
   }
+  if (eventName === GraphEvents.ON_RUN_STEP_CLOSED) {
+    const closed = data as { status?: string };
+    return closed.status != null && closed.status !== ''
+      ? `Step ${closed.status}`
+      : 'Step closed';
+  }
   if (eventName === GraphEvents.ON_MESSAGE_DELTA) {
     return 'Streaming…';
   }

package/src/types/graph.ts

@@ -17,6 +17,13 @@ import type {
   SummarizeStartEvent,
   SummarizeDeltaEvent,
 } from '@/types/summarize';
+import type {
+  RunStep,
+  RunStepDeltaEvent,
+  RunStepClosedEvent,
+  MessageDeltaEvent,
+  ReasoningDeltaEvent,
+} from '@/types/stream';
 import type {
   ToolMap,
   ToolSessionMap,
@@ -25,12 +32,6 @@ import type {
   LCTool,
   ToolExecuteBatchRequest,
 } from '@/types/tools';
-import type {
-  RunStep,
-  RunStepDeltaEvent,
-  MessageDeltaEvent,
-  ReasoningDeltaEvent,
-} from '@/types/stream';
 import type {
   TokenCounter,
   StreamLimits,
@@ -134,6 +135,7 @@ export interface EventHandler {
       | ModelEndData
       | RunStep
       | RunStepDeltaEvent
+      | RunStepClosedEvent
       | MessageDeltaEvent
       | ReasoningDeltaEvent
       | SummarizeStartEvent
@@ -597,6 +599,7 @@ export type SubagentUpdatePhase =
   | 'run_step'
   | 'run_step_delta'
   | 'run_step_completed'
+  | 'run_step_closed'
   | 'message_delta'
   | 'reasoning_delta'
   | 'stop'

package/src/types/hitl.ts

@@ -165,15 +165,37 @@ 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`).
@@ -184,6 +206,12 @@ 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
@@ -207,6 +235,12 @@ 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/src/types/stream.ts

@@ -8,6 +8,7 @@ import type {
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
+import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicContentBlock } from '@/llm/anthropic/types';
 import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
@@ -50,20 +51,30 @@ start, stream and end are associated with slightly different data payload.
 Please see the documentation for EventData for more details. */
 export type EventName = string;
 
+export type RunStepStatus =
+  | 'in_progress'
+  | 'completed'
+  | 'cancelled'
+  | 'failed';
+
 export type RunStep = {
-  // id: string;
-  // object: 'thread.run.step'; // Updated from 'run.step' # missing
-  // created_at: number;
-  // run_id: string;
-  // assistant_id: string;
-  // thread_id: string;
   type: StepTypes;
-  // status: 'in_progress' | 'completed' | 'failed' | 'cancelled'; // Add other possible status values if needed
-  // cancelled_at: number | null;
-  // completed_at: number | null;
-  // expires_at: number;
-  // failed_at: number | null;
-  // last_error: string | null;
+  /** Epoch ms when the step was dispatched. */
+  created_at?: number;
+  /**
+   * Lifecycle status; terminal values are stamped when the step closes.
+   * Invariant (enforced by `closeRunStep`, not the type, to stay wire-compatible
+   * with the OpenAI Assistants shape): a terminal status sets exactly one
+   * matching `*_at` field; first close wins and `cancelled`/`failed` are
+   * immutable once stamped.
+   */
+  status?: RunStepStatus;
+  /** Epoch ms when the step closed with status `completed`. */
+  completed_at?: number;
+  /** Epoch ms when the step closed with status `cancelled` (abort/halt). */
+  cancelled_at?: number;
+  /** Epoch ms when the step closed with status `failed`. */
+  failed_at?: number;
   id: string; // #new
   runId?: string; // #new
   agentId?: string; // #new - tracks which agent this step belongs to
@@ -107,6 +118,44 @@ export interface RunStepDeltaEvent {
   delta: ToolCallDelta;
 }
 
+/**
+ * Terminal signal for a run step, emitted exactly once per step when it
+ * finishes (`completed`), is aborted/halted (`cancelled`), or the run errors
+ * (`failed`). The `id` is top-level so callback echoes dedupe like other
+ * step-scoped events.
+ */
+export interface RunStepClosedEvent {
+  id: string;
+  index: number;
+  type: StepTypes;
+  status: Exclude<RunStepStatus, 'in_progress'>;
+  /** Epoch ms when the step was dispatched, when known. */
+  created_at?: number;
+  /** Epoch ms when the step reached its terminal status. */
+  closed_at: number;
+  runId?: string;
+  agentId?: string;
+  groupId?: number;
+  stepIndex?: number;
+}
+
+export type RecordStepCompletionOptions = {
+  /** The completing tool call, when the step tracks pending completions. */
+  toolCallId?: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Producer-stamped completion time (epoch ms). Carried through so a slow
+   * host completion handler cannot inflate the recorded step duration.
+   */
+  at?: number;
+};
+
+export type RunStepCloseOptions = {
+  /** Epoch ms for the terminal stamp; defaults to `Date.now()` at close time. */
+  at?: number;
+  metadata?: Record<string, unknown>;
+};
+
 export type StepDetails = MessageCreationDetails | ToolCallsDetails;
 
 export type SummaryCompleted = {
@@ -179,6 +228,8 @@ export type ToolCompleteEvent = ToolCallCompleted & {
   /** The content index of the tool call */
   index: number;
   type: 'tool_call';
+  /** Epoch ms when this tool call's completion was dispatched. */
+  completed_at?: number;
 };
 
 export type ToolCallsDetails = {
@@ -285,6 +336,8 @@ export type MessageDeltaUpdate = {
   type: ContentTypes.TEXT;
   text: string;
   tool_call_ids?: string[];
+  /** Provider-supplied source citations, accumulated across deltas. */
+  citations?: Anthropic.TextCitation[];
 };
 export type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string };
 

package/src/utils/handlers.ts

@@ -30,6 +30,10 @@ interface HandlerCallbacks {
     event: GraphEvents.ON_RUN_STEP_DELTA,
     data: t.StreamEventData
   ) => void;
+  onRunStepClosed?: (
+    event: GraphEvents.ON_RUN_STEP_CLOSED,
+    data: t.RunStepClosedEvent
+  ) => void;
   onMessageDelta?: (
     event: GraphEvents.ON_MESSAGE_DELTA,
     data: t.StreamEventData
@@ -88,6 +92,15 @@ export function createHandlers(callbacks?: HandlerCallbacks): {
       },
     },
 
+    [GraphEvents.ON_RUN_STEP_CLOSED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_CLOSED,
+        data: t.StreamEventData
+      ): void => {
+        callbacks?.onRunStepClosed?.(event, data as t.RunStepClosedEvent);
+      },
+    },
+
     [GraphEvents.ON_MESSAGE_DELTA]: {
       handle: (
         event: GraphEvents.ON_MESSAGE_DELTA,