mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 23:43:35 +00:00
📐 refactor: Normalize Stream Events Behind a ChatTransport Type (#16335)
* refactor: normalize stream events behind a ChatTransport type
Add the ChatTransport interface and a ChatEvent union discriminated by
type, covering every frame the client handles today: the created, sync
and final control frames, the step and side-channel { event, data }
frames, legacy content and text frames, attachments, errors, open and
abort. Types only; nothing consumes them yet.
* fix: type the stream frames the server actually sends
Assistants final frames carry a partial requestMessage, aborts can send
title: null, Assistants content frames omit userMessageId, and the error
event body can be a bare string or { error, generationProtocolVersion }.
Widen the frame types to admit each.
* fix: admit the remaining step, attachment and error payloads
on_agent_update also carries a { runId, message } status line when
sequential outputs are hidden, on_run_step_completed can arrive without
a result, a published run artifact is a plain TFile, and sendError marks
its body with error: true. The frame types now admit each.
This commit is contained in:
parent
f1bc07b2c7
commit
2f8a207317
2 changed files with 262 additions and 0 deletions
|
|
@ -45,6 +45,7 @@ export * from './types/web';
|
|||
export * from './types/graph';
|
||||
export * from './types/insights';
|
||||
export * from './types/traces';
|
||||
export * from './types/transport';
|
||||
export * from './types/subagents';
|
||||
export * from './types/queuedTurns';
|
||||
/* access permissions */
|
||||
|
|
|
|||
261
packages/data-provider/src/types/transport.ts
Normal file
261
packages/data-provider/src/types/transport.ts
Normal file
|
|
@ -0,0 +1,261 @@
|
|||
import type {
|
||||
StepEvents,
|
||||
UsageEvents,
|
||||
SteerEvents,
|
||||
ApprovalEvents,
|
||||
ActivityLabelEvents,
|
||||
ReasoningLabelEvents,
|
||||
TPendingSteer,
|
||||
SubagentUpdateEvent,
|
||||
TTokenUsageEvent,
|
||||
PtcToolCallEvent,
|
||||
TContextUsageEvent,
|
||||
TSteerAppliedEvent,
|
||||
TSteerUpdatedEvent,
|
||||
TActivityLabelEvent,
|
||||
TReasoningLabelEvent,
|
||||
SandboxStartingEvent,
|
||||
TReasoningLabelAttemptEvent,
|
||||
} from './runs';
|
||||
import type { TMessage, TPayload, TConversation } from '../types';
|
||||
import type { StreamContentData } from './content';
|
||||
import type { TAttachment } from '../schemas';
|
||||
import type { Agents } from './agents';
|
||||
import type { TFile } from './files';
|
||||
|
||||
/**
|
||||
* Wire frames: the JSON the server writes into the `data:` line of an SSE
|
||||
* `message` event. The server tells them apart by their keys, not by a tag,
|
||||
* so these mirror the emitters (`sendEvent` in `packages/api/src/utils/events.ts`
|
||||
* and the `ServerSentEvent` types beside it) and are normalized into
|
||||
* {@link ChatEvent} by the client transport.
|
||||
*/
|
||||
|
||||
/** `{ created: true }`: the user message was saved and generation started. */
|
||||
export type ChatCreatedFrame = {
|
||||
created: true;
|
||||
message: Partial<TMessage>;
|
||||
/** Present on resumable streams only. */
|
||||
streamId?: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* `{ sync: true }`: server-assigned ids for the turn (Assistants), or the
|
||||
* snapshot a reconnecting client rebuilds from (resumable streams).
|
||||
*/
|
||||
export type ChatSyncFrame = {
|
||||
sync: true;
|
||||
conversationId?: string;
|
||||
thread_id?: string;
|
||||
messages?: TMessage[];
|
||||
requestMessage?: Partial<TMessage>;
|
||||
responseMessage?: Partial<TMessage>;
|
||||
resumeState?: Agents.ResumeState;
|
||||
/** Frames published before the reconnect that the snapshot does not cover. */
|
||||
pendingEvents?: ChatFrame[];
|
||||
};
|
||||
|
||||
/** `{ final: true }`: the terminal frame of a completed, errored or aborted turn. */
|
||||
export type ChatFinalFrame = {
|
||||
final: true;
|
||||
/** The terminal status committed without its payload; refetch instead of rendering. */
|
||||
reconcile?: boolean;
|
||||
reconcileReason?: 'terminal_payload_missing' | 'generation_replaced' | 'abort_persistence_failed';
|
||||
terminalStatus?: 'complete' | 'error' | 'aborted';
|
||||
generationCreatedAt?: number;
|
||||
generationProtocolVersion?: number;
|
||||
/** Assistants runs send only `parentMessageId` and `thread_id` here. */
|
||||
requestMessage?: Partial<TMessage> | null;
|
||||
responseMessage?: Partial<TMessage> | null;
|
||||
conversation?: Partial<TConversation> | null;
|
||||
runMessages?: TMessage[];
|
||||
/** `null` when an abort lands before the conversation has a title. */
|
||||
title?: string | null;
|
||||
aborted?: boolean;
|
||||
earlyAbort?: boolean;
|
||||
/** Steers that never reached an injection boundary, handed back as queued turns. */
|
||||
pendingSteers?: TPendingSteer[];
|
||||
error?: { message: string };
|
||||
};
|
||||
|
||||
/** `{ event: 'title' }`: a generated conversation title. */
|
||||
export type ChatTitleFrame = {
|
||||
event: 'title';
|
||||
data?: {
|
||||
conversationId?: string;
|
||||
title?: string;
|
||||
};
|
||||
};
|
||||
|
||||
/** The status line `on_agent_update` carries when sequential outputs are hidden. */
|
||||
export type ChatAgentStatusUpdate = {
|
||||
runId?: string;
|
||||
message: string;
|
||||
};
|
||||
|
||||
/** A run artifact publishes a plain file; tool outputs add message metadata. */
|
||||
export type ChatAttachment = TAttachment | TFile;
|
||||
|
||||
/**
|
||||
* `{ event, data }` for the agent graph's step events, dispatched to the step
|
||||
* handler. Wider than the handler's own types where emitters send more shapes.
|
||||
*/
|
||||
export type ChatStepFrame =
|
||||
| { event: StepEvents.ON_RUN_STEP; data: Agents.RunStep }
|
||||
| { event: StepEvents.ON_AGENT_UPDATE; data: Agents.AgentUpdate | ChatAgentStatusUpdate }
|
||||
| { event: StepEvents.ON_MESSAGE_DELTA; data: Agents.MessageDeltaEvent }
|
||||
| { event: StepEvents.ON_REASONING_DELTA; data: Agents.ReasoningDeltaEvent }
|
||||
| { event: StepEvents.ON_RUN_STEP_DELTA; data: Agents.RunStepDeltaEvent }
|
||||
| { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result?: Agents.ToolEndEvent | null } }
|
||||
| { event: StepEvents.ON_RUN_STEP_CLOSED; data: Agents.RunStepClosedEvent }
|
||||
| { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }
|
||||
| { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent }
|
||||
| { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent }
|
||||
| { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent }
|
||||
| { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent }
|
||||
| { event: StepEvents.ON_PTC_TOOL_CALL; data: PtcToolCallEvent };
|
||||
|
||||
/** Any `{ event, data }` frame: step events plus the named side channels. */
|
||||
export type ChatEventFrame =
|
||||
| ChatTitleFrame
|
||||
| ChatStepFrame
|
||||
| { event: 'attachment'; data: ChatAttachment }
|
||||
| { event: UsageEvents.ON_CONTEXT_USAGE; data: TContextUsageEvent }
|
||||
| { event: UsageEvents.ON_TOKEN_USAGE; data: TTokenUsageEvent }
|
||||
| { event: ApprovalEvents.ON_PENDING_ACTION; data: Agents.PendingAction }
|
||||
| { event: SteerEvents.ON_STEER_APPLIED; data: TSteerAppliedEvent }
|
||||
| { event: SteerEvents.ON_STEER_UPDATED; data: TSteerUpdatedEvent }
|
||||
| { event: ActivityLabelEvents.ON_ACTIVITY_LABEL; data: TActivityLabelEvent }
|
||||
| { event: ReasoningLabelEvents.ON_REASONING_LABEL; data: TReasoningLabelEvent }
|
||||
| { event: ReasoningLabelEvents.ON_REASONING_LABEL_ATTEMPT; data: TReasoningLabelAttemptEvent };
|
||||
|
||||
/** Cumulative text from legacy (non-agent) streams, keyed by `message: true`. */
|
||||
export type ChatTextFrame = {
|
||||
message: true;
|
||||
text?: string;
|
||||
/** Older emitters name the cumulative text `response`. */
|
||||
response?: string;
|
||||
messageId?: string;
|
||||
parentMessageId?: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* A content part streamed with its message ids (Assistants). Unlike
|
||||
* `TContentData`, `userMessageId` is optional: the Assistants emitters omit it.
|
||||
*/
|
||||
export type ChatContentFrame = StreamContentData & {
|
||||
messageId: string;
|
||||
conversationId: string;
|
||||
thread_id: string;
|
||||
userMessageId?: string;
|
||||
stream?: boolean;
|
||||
};
|
||||
|
||||
/** Every JSON body the server writes on the `message` event. */
|
||||
export type ChatFrame =
|
||||
| ChatCreatedFrame
|
||||
| ChatSyncFrame
|
||||
| ChatFinalFrame
|
||||
| ChatEventFrame
|
||||
| ChatContentFrame
|
||||
| ChatTextFrame;
|
||||
|
||||
/**
|
||||
* The body of the SSE `error` event: a bare message string (`handleError`),
|
||||
* `{ error, generationProtocolVersion }` from the agents stream route, or a
|
||||
* failed turn's partial request/response pair.
|
||||
*/
|
||||
export type ChatErrorData =
|
||||
| string
|
||||
| {
|
||||
text?: string;
|
||||
message?: string;
|
||||
/** `true` from `sendError` once headers are sent, else the reason. */
|
||||
error?: boolean | string | { message?: string };
|
||||
generationProtocolVersion?: number;
|
||||
conversation?: Partial<TConversation>;
|
||||
requestMessage?: TMessage;
|
||||
responseMessage?: TMessage;
|
||||
};
|
||||
|
||||
/**
|
||||
* A stream event after normalization, discriminated by `type` the way
|
||||
* `TMessageContentParts` is. The AI SDK counterpart of this union is
|
||||
* `UIMessageChunk`; the equivalents are noted per member where one exists.
|
||||
*/
|
||||
export type ChatEvent =
|
||||
/** The connection opened. No AI SDK chunk; the SDK tracks this as `status: 'submitted'`. */
|
||||
| { type: 'open' }
|
||||
/** AI SDK: `start` (carries `messageId`). */
|
||||
| { type: 'created'; data: ChatCreatedFrame }
|
||||
/** No AI SDK equivalent: server id reconciliation and resume snapshots. */
|
||||
| { type: 'sync'; data: ChatSyncFrame }
|
||||
/** AI SDK: `finish`. A `reconcile` frame is still `final`; the consumer decides. */
|
||||
| { type: 'final'; data: ChatFinalFrame }
|
||||
/** AI SDK: a `data-*` part. */
|
||||
| { type: 'title'; data: ChatTitleFrame }
|
||||
/**
|
||||
* AI SDK: `file` / `source-url`. Arrives as a named SSE `attachment` event
|
||||
* on standard streams and as `{ event: 'attachment' }` on resumable ones.
|
||||
*/
|
||||
| { type: 'attachment'; data: ChatAttachment }
|
||||
/** AI SDK: `message-metadata`. */
|
||||
| { type: 'context_usage'; data: TContextUsageEvent }
|
||||
/** AI SDK: `message-metadata`. */
|
||||
| { type: 'token_usage'; data: TTokenUsageEvent }
|
||||
/** AI SDK: `tool-approval-request`. */
|
||||
| { type: 'pending_action'; data: Agents.PendingAction }
|
||||
/** No AI SDK equivalent: steering. */
|
||||
| { type: 'steer_applied'; data: TSteerAppliedEvent }
|
||||
/** No AI SDK equivalent: steering. */
|
||||
| { type: 'steer_updated'; data: TSteerUpdatedEvent }
|
||||
/** AI SDK: a transient `data-*` part. */
|
||||
| { type: 'activity_label'; data: TActivityLabelEvent }
|
||||
/** AI SDK: a transient `data-*` part. */
|
||||
| { type: 'reasoning_label'; data: TReasoningLabelEvent }
|
||||
/** Server bookkeeping that clients deliberately do not render. */
|
||||
| { type: 'reasoning_label_attempt'; data: TReasoningLabelAttemptEvent }
|
||||
/**
|
||||
* AI SDK: `text-delta`, `reasoning-delta`, `tool-input-*`, `tool-output-*`,
|
||||
* `start-step` and `finish-step`, which LibreChat carries as graph step events.
|
||||
*/
|
||||
| { type: 'step'; data: ChatStepFrame }
|
||||
/** AI SDK: `text-delta` and friends, for content-part streams (Assistants). */
|
||||
| { type: 'content'; data: ChatContentFrame }
|
||||
/** AI SDK: `text-delta`, except the text is cumulative rather than a delta. */
|
||||
| { type: 'text'; data: ChatTextFrame }
|
||||
/** AI SDK: `error`. `data` is `undefined` when the error body was not JSON. */
|
||||
| { type: 'error'; data?: ChatErrorData | null }
|
||||
/** AI SDK: `abort`. The caller closed a stream that was still open. */
|
||||
| { type: 'abort' };
|
||||
|
||||
export type ChatEventType = ChatEvent['type'];
|
||||
|
||||
/** The route and JSON body `createPayload` builds for one turn. */
|
||||
export type ChatTransportRequest = {
|
||||
server: string;
|
||||
payload: TPayload;
|
||||
};
|
||||
|
||||
export type ChatTransportOptions = {
|
||||
/**
|
||||
* Aborting closes the connection. When it interrupts a stream that was still
|
||||
* open, the transport emits `{ type: 'abort' }` synchronously before going quiet.
|
||||
*/
|
||||
signal: AbortSignal;
|
||||
/** Called synchronously for every event, in wire order. */
|
||||
onEvent: (event: ChatEvent) => void;
|
||||
};
|
||||
|
||||
/**
|
||||
* Carries one turn from request to terminal event. Implementations own the
|
||||
* wire (connection, framing, auth refresh); callers only see {@link ChatEvent}s.
|
||||
*
|
||||
* AI SDK: `ChatTransport`. `send` corresponds to `sendMessages`, returning
|
||||
* through a callback rather than a `ReadableStream` so handlers keep running
|
||||
* synchronously inside the frame that produced them. `reconnectToStream` has
|
||||
* no counterpart yet; resume still lives in `useResumableSSE`.
|
||||
*/
|
||||
export interface ChatTransport<TRequest = ChatTransportRequest> {
|
||||
send(request: TRequest, options: ChatTransportOptions): void;
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue