@librechat/agents 3.1.85 → 3.1.87

package/src/session/__tests__/handlers.test.ts

@@ -0,0 +1,161 @@
+import { ContentTypes, GraphEvents, StepTypes } from '@/common';
+import { composeEventHandlers } from '@/events';
+import { createRunHandlers } from '@/session';
+import type { AgentSessionStreamEvent } from '@/session';
+import type * as t from '@/types';
+
+describe('createRunHandlers', () => {
+  it('emits live session events through the same graph handlers before user handlers', async () => {
+    const liveEvents: AgentSessionStreamEvent[] = [];
+    let liveEventCountSeenByUserHandler = 0;
+    const handlerResult = createRunHandlers({
+      runId: 'run_live',
+      threadId: 'thread_live',
+      onEvent: (event) => {
+        liveEvents.push(event);
+      },
+      userHandlers: {
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (): void => {
+            liveEventCountSeenByUserHandler = liveEvents.length;
+          },
+        },
+      },
+    });
+
+    await handlerResult.handlers[GraphEvents.ON_RUN_STEP].handle(
+      GraphEvents.ON_RUN_STEP,
+      {
+        stepIndex: 0,
+        id: 'message_step',
+        type: StepTypes.MESSAGE_CREATION,
+        index: 0,
+        stepDetails: {
+          type: StepTypes.MESSAGE_CREATION,
+          message_creation: { message_id: 'message_step' },
+        },
+        usage: null,
+      } satisfies t.RunStep
+    );
+    await handlerResult.handlers[GraphEvents.ON_MESSAGE_DELTA].handle(
+      GraphEvents.ON_MESSAGE_DELTA,
+      {
+        id: 'message_step',
+        delta: { content: [{ type: 'text', text: 'hello' }] },
+      } satisfies t.MessageDeltaEvent
+    );
+
+    expect(liveEvents.map((event) => event.type)).toEqual([
+      'run.started',
+      'message.delta',
+    ]);
+    expect(liveEventCountSeenByUserHandler).toBe(2);
+    expect(handlerResult.contentParts[0]).toEqual({
+      type: 'text',
+      text: 'hello',
+    });
+  });
+
+  it('composes adapter and host handlers in order for the same graph event', async () => {
+    const calls: string[] = [];
+    const handlers = composeEventHandlers(
+      {
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (): void => {
+            calls.push('adapter');
+          },
+        },
+      },
+      {
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (): void => {
+            calls.push('host');
+          },
+        },
+      }
+    );
+
+    await handlers[GraphEvents.ON_MESSAGE_DELTA].handle(
+      GraphEvents.ON_MESSAGE_DELTA,
+      {
+        id: 'message_step',
+        delta: { content: [{ type: 'text', text: 'hello' }] },
+      } satisfies t.MessageDeltaEvent
+    );
+
+    expect(calls).toEqual(['adapter', 'host']);
+  });
+
+  it('accumulates partial usage metadata without corrupting totals', async () => {
+    jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const handlerResult = createRunHandlers({
+      runId: 'run_usage',
+      threadId: 'thread_usage',
+    });
+
+    await handlerResult.handlers[GraphEvents.CHAT_MODEL_END].handle(
+      GraphEvents.CHAT_MODEL_END,
+      {
+        output: { usage_metadata: { input_tokens: 4 } },
+      } as t.ModelEndData
+    );
+    await handlerResult.handlers[GraphEvents.CHAT_MODEL_END].handle(
+      GraphEvents.CHAT_MODEL_END,
+      {
+        output: { usage_metadata: { output_tokens: 6 } },
+      } as t.ModelEndData
+    );
+
+    expect(handlerResult.usage).toEqual({
+      inputTokens: 4,
+      outputTokens: 6,
+      totalTokens: 10,
+    });
+  });
+
+  it('does not emit tool completion events for summary completions', async () => {
+    const liveEvents: AgentSessionStreamEvent[] = [];
+    const handlerResult = createRunHandlers({
+      runId: 'run_summary',
+      threadId: 'thread_summary',
+      onEvent: (event) => {
+        liveEvents.push(event);
+      },
+    });
+    const summary: t.SummaryContentBlock = {
+      type: ContentTypes.SUMMARY,
+      content: [{ type: ContentTypes.TEXT, text: 'summary text' }],
+      tokenCount: 4,
+    };
+
+    await handlerResult.handlers[GraphEvents.ON_RUN_STEP].handle(
+      GraphEvents.ON_RUN_STEP,
+      {
+        stepIndex: 0,
+        id: 'summary_step',
+        type: StepTypes.MESSAGE_CREATION,
+        index: 0,
+        stepDetails: {
+          type: StepTypes.MESSAGE_CREATION,
+          message_creation: { message_id: 'summary_step' },
+        },
+        summary,
+        usage: null,
+      } satisfies t.RunStep
+    );
+    await handlerResult.handlers[GraphEvents.ON_RUN_STEP_COMPLETED].handle(
+      GraphEvents.ON_RUN_STEP_COMPLETED,
+      {
+        result: {
+          id: 'summary_step',
+          index: 0,
+          type: 'summary',
+          summary,
+        },
+      }
+    );
+
+    expect(liveEvents.map((event) => event.type)).toEqual(['run.started']);
+    expect(handlerResult.contentParts[0]).toBe(summary);
+  });
+});

package/src/session/handlers.ts

@@ -0,0 +1,272 @@
+import type { UsageMetadata } from '@langchain/core/messages';
+import { GraphEvents } from '@/common';
+import { ModelEndHandler, ToolEndHandler } from '@/events';
+import { createContentAggregator } from '@/stream';
+import type * as t from '@/types';
+import type {
+  AgentSessionHandlersResult,
+  AgentSessionStreamEvent,
+  AgentSessionUsage,
+} from './types';
+import { createTimestamp } from './ids';
+import { toJsonValue } from './messageSerialization';
+
+type CompletedRunStepResult =
+  | t.ToolEndEvent
+  | (t.SummaryCompleted & { id: string; index: number });
+
+function isToolCompletion(
+  result: CompletedRunStepResult
+): result is t.ToolEndEvent {
+  return 'tool_call' in result;
+}
+
+function createEventFactory(params: {
+  runId: string;
+  threadId: string;
+}): (
+  type: AgentSessionStreamEvent['type'],
+  data?: unknown
+) => AgentSessionStreamEvent {
+  let sequence = 0;
+  return (type, data) => ({
+    type,
+    sequence: sequence++,
+    runId: params.runId,
+    threadId: params.threadId,
+    timestamp: createTimestamp(),
+    ...(typeof data !== 'undefined' ? { data: toJsonValue(data) } : {}),
+  });
+}
+
+function getTokenCount(value: number | null | undefined): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function updateUsage(usage: AgentSessionUsage, data: t.ModelEndData): void {
+  const metadata = data?.output?.usage_metadata as
+    | Partial<UsageMetadata>
+    | undefined;
+  if (!metadata) {
+    return;
+  }
+  const inputTokens = getTokenCount(metadata.input_tokens);
+  const outputTokens = getTokenCount(metadata.output_tokens);
+  const totalTokens =
+    metadata.total_tokens == null
+      ? inputTokens + outputTokens
+      : getTokenCount(metadata.total_tokens);
+  usage.inputTokens += inputTokens;
+  usage.outputTokens += outputTokens;
+  usage.totalTokens += totalTokens;
+}
+
+async function callUserHandler(params: {
+  userHandlers?: Record<string, t.EventHandler>;
+  event: string;
+  data: Parameters<t.EventHandler['handle']>[1];
+  metadata?: Record<string, unknown>;
+  graph?: Parameters<t.EventHandler['handle']>[3];
+}): Promise<void> {
+  const handler = params.userHandlers?.[params.event];
+  if (!handler) {
+    return;
+  }
+  await handler.handle(
+    params.event,
+    params.data,
+    params.metadata,
+    params.graph
+  );
+}
+
+export function createRunHandlers(params: {
+  runId: string;
+  threadId: string;
+  userHandlers?: Record<string, t.EventHandler>;
+  onEvent?: (event: AgentSessionStreamEvent) => void;
+}): AgentSessionHandlersResult {
+  const { contentParts, aggregateContent } = createContentAggregator();
+  const steps: t.RunStep[] = [];
+  const usage: AgentSessionUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+  };
+  const events: AgentSessionStreamEvent[] = [];
+  const createEvent = createEventFactory({
+    runId: params.runId,
+    threadId: params.threadId,
+  });
+  const emitEvent = (event: AgentSessionStreamEvent): void => {
+    events.push(event);
+    params.onEvent?.(event);
+  };
+  const toolEndHandler = new ToolEndHandler();
+  const modelEndHandler = new ModelEndHandler();
+
+  emitEvent(createEvent('run.started'));
+
+  const handlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        await modelEndHandler.handle(
+          event,
+          data as t.ModelEndData,
+          metadata,
+          graph
+        );
+        updateUsage(usage, data as t.ModelEndData);
+        emitEvent(createEvent('usage.updated', usage));
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.TOOL_END]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        await toolEndHandler.handle(
+          event,
+          data as t.StreamEventData,
+          metadata,
+          graph
+        );
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        const runStep = data as t.RunStep;
+        steps.push(runStep);
+        aggregateContent({ event: GraphEvents.ON_RUN_STEP, data: runStep });
+        if (runStep.stepDetails.type === 'tool_calls') {
+          emitEvent(createEvent('tool.started', runStep));
+        }
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        const delta = data as t.RunStepDeltaEvent;
+        aggregateContent({ event: GraphEvents.ON_RUN_STEP_DELTA, data: delta });
+        emitEvent(createEvent('tool.delta', delta));
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        const completed = data as unknown as { result: CompletedRunStepResult };
+        aggregateContent({
+          event: GraphEvents.ON_RUN_STEP_COMPLETED,
+          data: completed as { result: t.ToolEndEvent },
+        });
+        if (isToolCompletion(completed.result)) {
+          emitEvent(createEvent('tool.completed', completed));
+        }
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        const delta = data as t.MessageDeltaEvent;
+        aggregateContent({ event: GraphEvents.ON_MESSAGE_DELTA, data: delta });
+        emitEvent(createEvent('message.delta', delta));
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_REASONING_DELTA]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        const delta = data as t.ReasoningDeltaEvent;
+        aggregateContent({
+          event: GraphEvents.ON_REASONING_DELTA,
+          data: delta,
+        });
+        emitEvent(createEvent('reasoning.delta', delta));
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_SUMMARIZE_DELTA]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        aggregateContent({
+          event: GraphEvents.ON_SUMMARIZE_DELTA,
+          data: data as t.SummarizeDeltaData,
+        });
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+    [GraphEvents.ON_SUMMARIZE_COMPLETE]: {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        aggregateContent({
+          event: GraphEvents.ON_SUMMARIZE_COMPLETE,
+          data: data as t.SummarizeCompleteEvent,
+        });
+        await callUserHandler({
+          userHandlers: params.userHandlers,
+          event,
+          data,
+          metadata,
+          graph,
+        });
+      },
+    },
+  };
+
+  return { contentParts, steps, usage, events, handlers };
+}

package/src/session/ids.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from 'crypto';
+
+export function createSessionId(): string {
+  return randomUUID();
+}
+
+export function createEntryId(): string {
+  return randomUUID().replace(/-/g, '').slice(0, 12);
+}
+
+export function createRunId(): string {
+  return randomUUID();
+}
+
+export function createTimestamp(): string {
+  return new Date().toISOString();
+}

package/src/session/index.ts

@@ -0,0 +1,44 @@
+export { AgentSession, createAgentSession } from './AgentSession';
+export { JsonlSessionStore, SessionManager } from './JsonlSessionStore';
+export { createRunHandlers } from './handlers';
+export {
+  serializeMessage,
+  deserializeMessage,
+  extractTextFromContent,
+} from './messageSerialization';
+export type {
+  AgentSessionConfig,
+  AgentSessionCheckpointLookupOptions,
+  AgentSessionCheckpointReference,
+  AgentSessionCheckpointing,
+  AgentSessionCheckpointingOptions,
+  AgentSessionHandlersResult,
+  AgentSessionInput,
+  AgentSessionRunOptions,
+  AgentSessionRunResult,
+  AgentSessionStream,
+  AgentSessionStreamEvent,
+  AgentSessionUsage,
+  CreateSessionFileOptions,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  SerializedSessionMessage,
+  SessionBranchOptions,
+  SessionCompactOptions,
+  SessionCheckpointEntry,
+  SessionCompactionEntry,
+  SessionEntry,
+  SessionEntryBase,
+  SessionEntryType,
+  SessionForkOptions,
+  SessionHeader,
+  SessionLabelEntry,
+  SessionListItem,
+  SessionMessageEntry,
+  SessionPosition,
+  SessionRunEventEntry,
+  SessionStateEntry,
+  SessionSummaryEntry,
+  SessionTreeNode,
+} from './types';

package/src/session/messageSerialization.ts

@@ -0,0 +1,207 @@
+import {
+  AIMessage,
+  HumanMessage,
+  RemoveMessage,
+  SystemMessage,
+  ToolMessage,
+  BaseMessage,
+} from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { UsageMetadata } from '@langchain/core/messages';
+import type { JsonObject, JsonValue, SerializedSessionMessage } from './types';
+
+type MessageExtras = {
+  id?: string;
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: ToolCall[];
+  usage_metadata?: UsageMetadata;
+  additional_kwargs?: unknown;
+  response_metadata?: unknown;
+};
+
+const CIRCULAR_REFERENCE = '[Circular]';
+
+function isJsonPrimitive(
+  value: unknown
+): value is string | number | boolean | null {
+  return (
+    value == null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+function toJsonValueInternal(value: unknown, seen: WeakSet<object>): JsonValue {
+  if (isJsonPrimitive(value)) {
+    return Number.isNaN(value) ? null : value;
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return CIRCULAR_REFERENCE;
+    }
+    seen.add(value);
+    const result = value.map((item) => toJsonValueInternal(item, seen));
+    seen.delete(value);
+    return result;
+  }
+  if (value instanceof Error) {
+    if (seen.has(value)) {
+      return CIRCULAR_REFERENCE;
+    }
+    seen.add(value);
+    const result: JsonObject = {
+      name: value.name,
+      message: value.message,
+    };
+    if (value.stack != null && value.stack !== '') {
+      result.stack = value.stack;
+    }
+    if ('cause' in value && typeof value.cause !== 'undefined') {
+      result.cause = toJsonValueInternal(value.cause, seen);
+    }
+    for (const [key, nested] of Object.entries(value)) {
+      if (typeof nested !== 'undefined') {
+        result[key] = toJsonValueInternal(nested, seen);
+      }
+    }
+    seen.delete(value);
+    return result;
+  }
+  if (value !== null && typeof value === 'object') {
+    if (seen.has(value)) {
+      return CIRCULAR_REFERENCE;
+    }
+    seen.add(value);
+    const result: JsonObject = {};
+    for (const [key, nested] of Object.entries(value)) {
+      if (typeof nested !== 'undefined') {
+        result[key] = toJsonValueInternal(nested, seen);
+      }
+    }
+    seen.delete(value);
+    return result;
+  }
+  return String(value);
+}
+
+export function toJsonValue(value: unknown): JsonValue {
+  return toJsonValueInternal(value, new WeakSet<object>());
+}
+
+function toJsonObject(value: unknown): JsonObject | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+  return toJsonValue(value) as JsonObject;
+}
+
+function fromJsonValue(value: JsonValue): unknown {
+  return value;
+}
+
+export function serializeMessage(
+  message: BaseMessage
+): SerializedSessionMessage {
+  const extras = message as BaseMessage & MessageExtras;
+  const serialized: SerializedSessionMessage = {
+    messageType: message._getType(),
+    content: toJsonValue(message.content),
+  };
+  const additionalKwargs = toJsonObject(extras.additional_kwargs);
+  const responseMetadata = toJsonObject(extras.response_metadata);
+  const usageMetadata = toJsonObject(extras.usage_metadata);
+  if (additionalKwargs) {
+    serialized.additionalKwargs = additionalKwargs;
+  }
+  if (responseMetadata) {
+    serialized.responseMetadata = responseMetadata;
+  }
+  if (usageMetadata) {
+    serialized.usageMetadata = usageMetadata;
+  }
+  if (extras.id != null && extras.id !== '') {
+    serialized.id = extras.id;
+  }
+  if (extras.name != null && extras.name !== '') {
+    serialized.name = extras.name;
+  }
+  if (extras.tool_call_id != null && extras.tool_call_id !== '') {
+    serialized.toolCallId = extras.tool_call_id;
+  }
+  if (extras.tool_calls) {
+    serialized.toolCalls = toJsonValue(extras.tool_calls);
+  }
+  return serialized;
+}
+
+export function deserializeMessage(
+  serialized: SerializedSessionMessage
+): BaseMessage {
+  const common = {
+    content: fromJsonValue(serialized.content) as BaseMessage['content'],
+    additional_kwargs: serialized.additionalKwargs,
+    response_metadata: serialized.responseMetadata,
+    id: serialized.id,
+    name: serialized.name,
+  };
+  if (serialized.messageType === 'human') {
+    return new HumanMessage(common);
+  }
+  if (serialized.messageType === 'ai') {
+    return new AIMessage({
+      ...common,
+      tool_calls: serialized.toolCalls as ToolCall[] | undefined,
+      usage_metadata: serialized.usageMetadata as UsageMetadata | undefined,
+    });
+  }
+  if (serialized.messageType === 'system') {
+    return new SystemMessage(common);
+  }
+  if (serialized.messageType === 'tool') {
+    return new ToolMessage({
+      ...common,
+      tool_call_id: serialized.toolCallId ?? '',
+    });
+  }
+  if (serialized.messageType === 'remove') {
+    return new RemoveMessage({
+      additional_kwargs: serialized.additionalKwargs,
+      response_metadata: serialized.responseMetadata,
+      id: serialized.id ?? '',
+      name: serialized.name,
+    });
+  }
+  return new HumanMessage(common);
+}
+
+export function getMessageRole(message: BaseMessage): string {
+  const type = message._getType();
+  if (type === 'human') {
+    return 'user';
+  }
+  if (type === 'ai') {
+    return 'assistant';
+  }
+  return type;
+}
+
+export function extractTextFromContent(content: JsonValue): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return '';
+  }
+  const chunks: string[] = [];
+  for (const part of content) {
+    if (part != null && typeof part === 'object' && !Array.isArray(part)) {
+      const text = part.text;
+      if (typeof text === 'string') {
+        chunks.push(text);
+      }
+    }
+  }
+  return chunks.join('');
+}