From 2f8a207317442c0ebf7914f47d7c042ee77b2896 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 25 Sep 2026 09:26:12 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=90=20refactor:=20Normalize=20Stream?= =?UTF-8?q?=20Events=20Behind=20a=20ChatTransport=20Type=20(#16335)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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. --- packages/data-provider/src/index.ts | 1 + packages/data-provider/src/types/transport.ts | 261 ++++++++++++++++++ 2 files changed, 262 insertions(+) create mode 100644 packages/data-provider/src/types/transport.ts diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts index 44d862c3f6..b226ad4191 100644 --- a/packages/data-provider/src/index.ts +++ b/packages/data-provider/src/index.ts @@ -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 */ diff --git a/packages/data-provider/src/types/transport.ts b/packages/data-provider/src/types/transport.ts new file mode 100644 index 0000000000..369842cddf --- /dev/null +++ b/packages/data-provider/src/types/transport.ts @@ -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; + /** 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; + responseMessage?: Partial; + 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 | null; + responseMessage?: Partial | null; + conversation?: Partial | 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; + 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 { + send(request: TRequest, options: ChatTransportOptions): void; +}