📐 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:
Marco Beretta 2026-09-25 09:26:12 +02:00 • committed by GitHub
parent f1bc07b2c7
commit 2f8a207317
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 262 additions and 0 deletions

View file

@ -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 */

View 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;
}