Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛑 feat: Stop the Turn in Flight From the Chat Core (#17577)
Marco Beretta08a6e7fb28af
diff --git a/packages/chat/src/core/__tests__/chat.spec.ts b/packages/chat/src/core/__tests__/chat.spec.tsindex 806c0a892c..8ec339ab84 100644--- a/packages/chat/src/core/__tests__/chat.spec.ts+++ b/packages/chat/src/core/__tests__/chat.spec.ts@@ -1,6 +1,12 @@import { StepEvents, buildTree } from 'librechat-data-provider';import type { Agents, TMessage, TPayload, ChatEvent } from 'librechat-data-provider';-import type { ChatStream, ChatStatus, ChatTransport, ChatConnection } from '../types';+import type {+ ChatStream,+ ChatStatus,+ ChatTransport,+ ChatConnection,+ ChatAbortResult,+} from '../types';import type { ChatState, ChatInit } from '../chat';import { Chat } from '../chat';@@ -310,6 +316,21 @@ describe('Chat', () => {expect(chat.status).toBe('submitted');expect(chat.connection).toBe('idle');});++ it('releases a stop still waiting for the server, and the turn it stops', async () => {+ const { chat, transport } = setup({});+ transport.abort.mockImplementationOnce(() => new Promise<never>(() => undefined));+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ const stopped = chat.stop();+ await flush();++ chat.dispose();++ await expect(stopped).rejects.toThrow('The chat was disposed');+ await expect(sent).resolves.toBeUndefined();+ expect(chat.connection).toBe('idle');+ });});it('streams a turn whose first frame is a pause', async () => {@@ -479,6 +500,153 @@ describe('Chat', () => {expect(chat.status).toBe('ready');});+ it('cancels a start that has not attached yet', async () => {+ let signal: AbortSignal | undefined;+ const { chat, transport, onFinish } = setup(+ {},+ {+ sendMessages: jest.fn(+ (request) =>+ new Promise((_, reject) => {+ signal = request.abortSignal;+ request.abortSignal?.addEventListener('abort', () => reject(new Error('aborted')));+ }),+ ),+ },+ );++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;++ expect(signal?.aborted).toBe(true);+ expect(transport.abort).not.toHaveBeenCalled();+ /** The start reached the transport, so the server may run it: its end is unknown. */+ expect(chat.status).toBe('error');+ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({ isAbort: false, isDisconnect: true }),+ );+ });++ it.each(['stop', 'dispose'] as const)(+ 'closes a stream that arrives after %s without applying it',+ async (cancel) => {+ let open: (() => void) | undefined;+ const { chat, stream, state, onError, transport } = setup(+ {},+ {+ sendMessages: jest.fn(+ () =>+ new Promise((resolve) => {+ open = () => resolve({ status: 'stream', stream });+ }),+ ),+ },+ );++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ const cancelled = cancel === 'stop' ? chat.stop() : chat.dispose();+ stream.push(finalEvent());+ open?.();+ await sent;+ await cancelled;++ expect(stream.closed()).toBe(true);+ expect(state.messages[1].text).toBe('');+ /** A stop reports the cancelled start as a disconnect; a disposal reports nothing. */+ expect(onError).toHaveBeenCalledTimes(cancel === 'stop' ? 1 : 0);+ expect(transport.abort).toHaveBeenCalledTimes(cancel === 'stop' ? 1 : 0);+ },+ );++ it.each(['sendMessages'] as const)(+ 'stops while %s ignores the abort signal, closing the stream it opens later',+ async (opener) => {+ let open: (() => void) | undefined;+ const stream = createStream({ streamId: 'convo-1' });+ const pending = jest.fn(+ () =>+ new Promise<Awaited<ReturnType<ChatTransport['sendMessages']>>>((resolve) => {+ open = () => resolve({ status: 'stream', stream });+ }),+ );+ const { chat, onFinish, transport } = setup({}, { [opener]: pending });++ const started = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await started;+ /** A cancelled start may still run on the server. */+ expect(chat.status).toBe('error');+ open?.();+ await flush();++ expect(stream.closed()).toBe(true);+ expect(transport.abort).toHaveBeenCalledTimes(1);+ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ endpoint: 'agents', streamId: 'convo-1' }),+ );+ expect(onFinish).toHaveBeenCalledTimes(1);+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isDisconnect: true }));+ },+ );++ it('does not start a turn stopped while its optimistic messages were written', async () => {+ const { chat, transport, onFinish } = setup();+ const unsubscribe = chat.subscribe(() => {+ if (chat.messages.length > 0) {+ void chat.stop();+ }+ });++ await chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ unsubscribe();++ expect(transport.sendMessages).not.toHaveBeenCalled();+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ });++ it('does not write the optimistic messages of a turn stopped once its request was prepared', async () => {+ let prepared: (() => void) | undefined;+ const { chat, state, transport } = setup({+ prepareRequest: jest.fn(+ () =>+ new Promise((resolve) => {+ prepared = () => resolve({ payload, messages: [userMessage, placeholder] });+ }),+ ),+ });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ prepared?.();+ await Promise.resolve();+ const stopped = chat.stop();+ await sent;+ await stopped;++ expect(state.messages).toEqual([]);+ expect(transport.sendMessages).not.toHaveBeenCalled();+ });++ it('does not prepare a turn stopped as soon as it was submitted', async () => {+ const prepareRequest = jest.fn(() => ({ payload, messages: [userMessage, placeholder] }));+ const { chat, onFinish } = setup({ prepareRequest });+ const unsubscribe = chat.subscribe(() => {+ if (chat.status === 'submitted') {+ void chat.stop();+ }+ });++ await chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ unsubscribe();++ expect(prepareRequest).not.toHaveBeenCalled();+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ });+it('merges a prepared turn into the list as it stands when the turn is written', async () => {const loaded: TMessage = { ...userMessage, messageId: 'loaded-1', text: 'Loaded' };let prepared: (() => void) | undefined;@@ -510,6 +678,250 @@ describe('Chat', () => {await sent;});+ it('finishes a turn stopped during its optimistic write with its own response', async () => {+ const otherBranch: TMessage = { ...placeholder, messageId: 'other-1', parentMessageId: 'x' };+ const { chat, onFinish } = setup({+ prepareRequest: jest.fn(() => ({+ payload,+ messages: [userMessage, placeholder, otherBranch],+ responseMessageId: 'response-1',+ })),+ });+ const unsubscribe = chat.subscribe(() => {+ if (chat.messages.length > 0) {+ void chat.stop();+ }+ });++ await chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ unsubscribe();++ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({+ isAbort: true,+ message: expect.objectContaining({ messageId: 'response-1' }),+ }),+ );+ });++ it('cancels a start whose request is still being prepared, without writing it', async () => {+ let prepare: (value: { payload: TPayload; messages: TMessage[] }) => void = () => {};+ const { chat, transport, state, onFinish } = setup({+ prepareRequest: () =>+ new Promise((resolve) => {+ prepare = resolve;+ }),+ });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;+ prepare({ payload, messages: [userMessage, placeholder] });+ await flush();++ expect(chat.status).toBe('ready');+ expect(state.messages).toEqual([]);+ expect(transport.sendMessages).not.toHaveBeenCalled();+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ });++ it('stops an attached stream on the server and resolves once it ended', async () => {+ const { chat, stream, transport, onFinish } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push(finalEvent({ terminalStatus: 'aborted' }));+ return { success: true };+ });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();+ await chat.stop();++ expect(transport.abort).toHaveBeenCalledWith({+ chatId: 'convo-1',+ endpoint: 'agents',+ streamId: 'convo-1',+ generationCreatedAt: 100,+ });+ expect(chat.status).toBe('ready');+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ await sent;+ });++ it('reports a stopped stream that drops instead of ending as aborted', async () => {+ const { chat, stream, transport, onFinish, onError } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);+ return { success: true };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ await chat.stop();+ await sent;++ expect(chat.status).toBe('ready');+ expect(onError).not.toHaveBeenCalled();+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ });++ it('asks the host to reload a confirmed stop whose abort frame the dropped stream lost', async () => {+ const { chat, stream, transport, onFinish } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);+ return { success: true, aborted: 'convo-1' };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ await chat.stop();+ await sent;++ expect(onFinish).toHaveBeenLastCalledWith(+ expect.objectContaining({+ isAbort: true,+ isDisconnect: false,+ isSettled: true,+ conversationId: 'convo-1',+ }),+ );+ });++ it('reports a failed stop of a start that arrived after it', async () => {+ let open: (() => void) | undefined;+ const stream = createStream({ streamId: 'convo-1' });+ const { chat, transport, onError } = setup(+ {},+ {+ sendMessages: jest.fn(+ () =>+ new Promise((resolve) => {+ open = () => resolve({ status: 'stream', stream });+ }),+ ),+ },+ );+ transport.abort.mockImplementation(async () => ({ success: false, error: 'busy' }));++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;+ open?.();+ await flush();++ expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: 'busy' }));+ });++ it.each([true, false])(+ 'holds a stream that drops before the stop is answered until the answer (confirmed: %s)',+ async (confirmed) => {+ const { chat, stream, transport } = setup();+ let answer: (() => void) | undefined;+ transport.abort.mockImplementation(+ () =>+ new Promise((resolve) => {+ answer = () => resolve(confirmed ? { success: true } : { success: false });+ }),+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ const stopped = chat.stop();+ stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);+ await flush();+ expect(chat.status).toBe('streaming');+ answer?.();++ if (confirmed) {+ await stopped;+ await sent;+ expect(chat.status).toBe('ready');+ expect(chat.error).toBeUndefined();+ } else {+ await expect(stopped).rejects.toThrow('refused');+ await sent;+ expect(chat.status).toBe('error');+ }+ },+ );++ it('holds a dropped turn, and refuses the next one, until its stop is answered', async () => {+ const { chat, stream, transport } = setup();+ let answer: (() => void) | undefined;+ transport.abort.mockImplementation(+ () =>+ new Promise((resolve) => {+ answer = () => resolve({ success: true });+ }),+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ const stopped = chat.stop();+ stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);+ await flush();++ await expect(chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] })).rejects.toThrow(+ 'in flight',+ );+ answer?.();+ await stopped;+ await sent;++ expect(chat.status).toBe('ready');+ });++ it('rejects a refused stop and keeps streaming', async () => {+ const failure = new Error('abort failed');+ const { chat, stream, transport } = setup();+ transport.abort.mockRejectedValueOnce(failure);++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ await expect(chat.stop()).rejects.toBe(failure);+ expect(chat.status).toBe('streaming');+ stream.push(finalEvent());+ await sent;+ expect(chat.status).toBe('ready');+ });++ it('rejects a stop the server answered without stopping, and keeps streaming', async () => {+ const { chat, stream, transport } = setup();+ transport.abort.mockResolvedValueOnce({ success: false, error: 'Not the running generation' });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ await expect(chat.stop()).rejects.toThrow('Not the running generation');+ expect(chat.status).toBe('streaming');+ stream.push(finalEvent());+ await sent;+ });++ it('returns a live connection to idle on dispose', async () => {+ const { chat } = setup();+ void chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ expect(chat.connection).toBe('live');++ chat.dispose();++ expect(chat.connection).toBe('idle');+ });+it('drops its stream on dispose without reporting an error', async () => {const { chat, stream, onError, onFinish } = setup();@@ -564,6 +976,90 @@ describe('Chat', () => {expect(replaced.chat.status).toBe('ready');});+ it('stops a replacing generation on the server while it is still attaching', async () => {+ const { chat, transport } = setup(+ {},+ {+ sendMessages: jest.fn(async () => ({+ status: 'replaced' as const,+ generationProtocolVersion: 2,+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ })),+ reconnectToStream: jest.fn(() => new Promise<null>(() => undefined)),+ },+ );++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({+ endpoint: 'agents',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ }),+ );+ expect(chat.status).toBe('ready');+ });++ it('settles a replacement that finds nothing by the answer of a stop still in flight', async () => {+ let open: ((stream: ChatStream | null) => void) | undefined;+ let answer: ((result: ChatAbortResult) => void) | undefined;+ const { chat, onFinish } = setup(+ {},+ {+ sendMessages: jest.fn(async () => ({+ status: 'replaced' as const,+ generationProtocolVersion: 2,+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ })),+ reconnectToStream: jest.fn(+ () =>+ new Promise<ChatStream | null>((resolve) => {+ open = resolve;+ }),+ ),+ abort: jest.fn(+ () =>+ new Promise<ChatAbortResult>((resolve) => {+ answer = resolve;+ }),+ ),+ },+ );++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ const stopped = chat.stop();+ await flush();+ open?.(null);+ await flush();+ expect(onFinish).not.toHaveBeenCalled();++ answer?.({+ success: true,+ generationProtocolVersion: 2,+ aborted: 'convo-1',+ persistenceFailed: true,+ });+ await stopped;+ await sent;+ expect(onFinish).toHaveBeenCalledTimes(1);+ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({+ isAbort: true,+ isSettled: true,+ reconcileReason: 'abort_persistence_failed',+ }),+ );+ });+it('lets a completion callback start the next turn', async () => {let next: Promise<void> | undefined;const { chat, stream, transport } = setup({@@ -692,16 +1188,239 @@ describe('Chat', () => {})),});- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });- await flush();- stream.push(end === 'final' ? finalEvent() : ({ type: 'abort', data: {} } as ChatEvent));- await sent;+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(end === 'final' ? finalEvent() : ({ type: 'abort', data: {} } as ChatEvent));+ await sent;++ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({ message: expect.objectContaining({ messageId: 'response-1' }) }),+ );+ },+ );++ it('stops an Assistants run by its abort key and merges the messages the stop returns', async () => {+ const stream = createStream();+ const { chat, transport, onFinish } = setup(+ {+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'convo-1', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ transport.abort.mockResolvedValue({+ final: true,+ conversation: {},+ runMessages: [userMessage, { ...placeholder, text: 'Partial' }],+ });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ endpoint: 'assistants', abortKey: 'convo-1:response-1' }),+ );+ expect(chat.messages[1].text).toBe('Partial');+ expect(chat.status).toBe('ready');+ expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isAbort: true }));+ });++ it('settles an attached Assistants run a stop found already gone for the host to reconcile', async () => {+ const stream = createStream();+ const { chat, transport, onFinish } = setup(+ {+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'convo-1', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ transport.abort.mockResolvedValue(null);++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent;++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ endpoint: 'assistants', abortKey: 'convo-1:response-1' }),+ );+ expect(stream.closed()).toBe(true);+ expect(chat.status).toBe('ready');+ expect(onFinish).toHaveBeenLastCalledWith(+ expect.objectContaining({ isAbort: false, isSettled: true }),+ );+ });++ it('returns the conversation an Assistants stop created for a first turn under `new`', async () => {+ const stream = createStream();+ const { chat, transport } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'new', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ transport.abort.mockResolvedValue({+ final: true,+ conversation: { conversationId: 'convo-9' },+ runMessages: [userMessage, { ...placeholder, text: 'Partial' }],+ });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push({+ type: 'sync',+ data: { conversationId: 'convo-9', responseMessage: placeholder },+ } as ChatEvent);+ await flush();+ const result = await chat.stop();+ await sent;++ expect(result).toEqual({ status: 'stopped', conversationId: 'convo-9' });+ });++ it('replaces the list with the run messages a stop returns, dropping rows the run deleted', async () => {+ const stream = createStream();+ const unfinished: TMessage = { ...placeholder, messageId: 'tool-1', text: '' };+ const { chat, transport } = setup(+ {+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'convo-1', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder, unfinished],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ const runMessages = [userMessage, { ...placeholder, text: 'Partial' }];+ transport.abort.mockResolvedValue({ final: true, conversation: {}, runMessages });++ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;++ expect(chat.messages).toEqual(runMessages);+ });++ it('stops a late Assistants start by its abort key', async () => {+ let open: (() => void) | undefined;+ const stream = createStream();+ const { chat, transport } = setup(+ {+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'convo-1', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ {+ sendMessages: jest.fn(+ () =>+ new Promise((resolve) => {+ open = () => resolve({ status: 'stream', stream });+ }),+ ),+ },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;+ open?.();+ await flush();++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ endpoint: 'assistants', abortKey: 'convo-1:response-1' }),+ );+ });++ it('does not merge a delayed stop of a dropped run into a newer turn', async () => {+ const first = createStream();+ const second = createStream();+ let answer: (() => void) | undefined;+ const { chat, transport } = setup(+ {+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', conversationId: 'convo-1', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ {+ sendMessages: jest+ .fn()+ .mockResolvedValueOnce({ status: 'stream', stream: first })+ .mockResolvedValueOnce({ status: 'stream', stream: second }),+ },+ );+ transport.abort.mockImplementation(+ () =>+ new Promise((resolve) => {+ answer = () =>+ resolve({+ final: true,+ conversation: {},+ runMessages: [{ ...placeholder, text: 'Old' }],+ });+ }),+ );+ const firstTurn = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ first.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);+ await firstTurn;+ const stopped = chat.stop();+ const secondTurn = chat.continue({ messageId: 'response-1' });+ await flush();+ answer?.();+ await stopped;++ expect(chat.messages[1].text).toBe('');+ second.push(finalEvent());+ await secondTurn;+ });++ it('stops an Assistants run by the ids its sync frame assigned', async () => {+ const stream = createStream();+ const { chat, transport } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ transport.abort.mockResolvedValue({ final: true, conversation: {}, runMessages: [] });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push({+ type: 'sync',+ data: { sync: true, conversationId: 'convo-9', responseMessage: { messageId: 'server-2' } },+ } as ChatEvent);+ await flush();++ await chat.stop();+ await sent;- expect(onFinish).toHaveBeenCalledWith(- expect.objectContaining({ message: expect.objectContaining({ messageId: 'response-1' }) }),- );- },- );+ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ abortKey: 'convo-9:server-2' }),+ );+ });it('refuses a replacement the server did not report under protocol v2', async () => {const { chat, transport, onError } = setup(@@ -747,6 +1466,38 @@ describe('Chat', () => {);});+ it('reports a run the stop found already finished as settled when its final frame is lost', async () => {+ const { chat, stream, transport, onFinish } = setup();+ transport.abort.mockImplementation(async () => {+ stream.close();+ return { success: false, settled: true, terminalStatus: 'complete' };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await chat.stop();+ await sent;++ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({ isAbort: false, isSettled: true }),+ );+ expect(chat.status).toBe('ready');+ });++ it('accepts a stop the run had already settled', async () => {+ const { chat, stream, transport } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push(finalEvent());+ return { success: false, settled: true, terminalStatus: 'complete' };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent;+ expect(chat.status).toBe('ready');+ });+it.each(['ERR_NETWORK', 'ERR_INTERNET_DISCONNECTED'])('reports a start that never got a response (%s) as a disconnect',async (code) => {@@ -764,6 +1515,36 @@ describe('Chat', () => {},);+ it('leaves a replacing generation running when the start it replaced was stopped', async () => {+ let open: (() => void) | undefined;+ const { chat, transport } = setup(+ {},+ {+ sendMessages: jest.fn(+ () =>+ new Promise((resolve) => {+ open = () =>+ resolve({+ status: 'replaced',+ generationProtocolVersion: 2,+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ });+ }),+ ),+ },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await chat.stop();+ await sent;+ open?.();+ await flush();++ expect(transport.abort).not.toHaveBeenCalled();+ });+it('reports a start the server settled before attaching for the host to reconcile', async () => {const { chat, onFinish } = setup({},@@ -835,7 +1616,170 @@ describe('Chat', () => {expect(regenerating.status).toBe('ready');});- describe('replacement responses', () => {+ describe('stop answers and reattachment targets', () => {+ const steer = { steerId: 'steer-1', text: 'Shorter' };++ it('hands back the steers a stop found uninjected, under the conversation it stopped', async () => {+ const { chat, stream, transport } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push(finalEvent({ terminalStatus: 'aborted' }));+ return { success: true, aborted: 'stream-7', pendingSteers: [steer] };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ /** The answer names the stopped stream; the conversation is the one the chat knows. */+ await expect(chat.stop()).resolves.toEqual({+ status: 'stopped',+ conversationId: 'convo-1',+ pendingSteers: [steer],+ });+ await sent;+ });++ it('hands back no steers from a stop the run had already settled or could not save', async () => {+ for (const answer of [+ { settled: true, terminalStatus: 'complete' as const },+ { persistenceFailed: true },+ ]) {+ const { chat, stream, transport } = setup();+ transport.abort.mockImplementation(async () => {+ stream.push(finalEvent({ terminalStatus: 'aborted' }));+ return { success: true, aborted: 'convo-1', pendingSteers: [steer], ...answer };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({+ status: 'stopped',+ conversationId: 'convo-1',+ });+ await sent;+ }+ });++ it('reports a turn under `new` it saw no frame for as unaddressable, leaving it attached', async () => {+ const stream = createStream();+ const { chat, transport } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });++ expect(transport.abort).not.toHaveBeenCalled();+ expect(chat.status).toBe('streaming');+ stream.push(finalEvent());+ await sent;+ });++ it('reports a start cancelled before it reached the transport as stopped', async () => {+ const { chat, transport } = setup({+ prepareRequest: jest.fn(() => new Promise<never>(() => undefined)),+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent.catch(() => undefined);+ expect(transport.sendMessages).not.toHaveBeenCalled();+ });++ it('sends no stop for a late start it cannot name', async () => {+ let open: ((result: { status: 'stream'; stream: ChatStream }) => void) | undefined;+ const late = createStream();+ const { chat, transport, onError } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ {+ sendMessages: jest.fn(+ () =>+ new Promise<{ status: 'stream'; stream: ChatStream }>((resolve) => {+ open = resolve;+ }),+ ),+ },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });+ open?.({ status: 'stream', stream: late });+ await sent.catch(() => undefined);+ await flush();++ expect(late.closed()).toBe(true);+ expect(transport.abort).not.toHaveBeenCalled();+ expect(onError).toHaveBeenCalledTimes(1);+ });++ it("stops an Assistants run by the ids its sync frame named, from that frame's own callback", async () => {+ const stream = createStream();+ const stops: Promise<unknown>[] = [];+ const harness: { chat?: Chat } = {};+ const { chat, transport } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ onEvent: (event) => {+ if (event.type === 'sync' && harness.chat) {+ stops.push(harness.chat.stop());+ }+ },+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ harness.chat = chat;+ transport.abort.mockImplementation(async () => {+ stream.push(finalEvent({ terminalStatus: 'aborted' }));+ return { final: true, conversation: {}, runMessages: [] };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ stream.push({+ type: 'sync',+ data: {+ conversationId: 'convo-9',+ responseMessage: { ...placeholder, messageId: 'response-9' },+ },+ } as ChatEvent);+ await sent;+ await Promise.all(stops);++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ abortKey: 'convo-9:response-9' }),+ );+ });++ it('reports nothing to stop as idle', async () => {+ const { chat, transport } = setup();++ await expect(chat.stop()).resolves.toEqual({ status: 'idle' });+ expect(transport.abort).not.toHaveBeenCalled();+ });+it('reports the response of a replacement that ended before any frame named it as unknown', async () => {const replacing = () => {const stream = createStream({ streamId: 'stream-2', generationCreatedAt: 200 });@@ -914,6 +1858,102 @@ describe('Chat', () => {expect.objectContaining({ ...options, chatId: 'convo-1', streamId: 'stream-2' }),);});++ it('stops a legacy first turn by the conversation its created frame named', async () => {+ const stream = createStream();+ const { chat, transport } = setup(+ {+ id: 'new',+ prepareRequest: jest.fn(() => ({+ payload: { ...payload, conversationId: 'new' },+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ })),+ },+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },+ );+ transport.abort.mockImplementation(async () => {+ stream.push({ type: 'abort', data: {} } as ChatEvent);+ return { success: true };+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push({+ type: 'created',+ data: { created: true, message: { ...userMessage, conversationId: 'convo-9' } },+ } as ChatEvent);+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent;+ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ abortKey: 'convo-9:response-1' }),+ );+ });++ it('reports a cancelled start the server may still run as a disconnect, not an abort', async () => {+ const { chat, onFinish } = setup(+ {},+ { sendMessages: jest.fn(() => new Promise<never>(() => undefined)) },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });+ await sent;++ expect(onFinish).toHaveBeenCalledTimes(1);+ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({ isAbort: false, isDisconnect: true }),+ );+ expect(chat.status).toBe('error');+ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });+ });++ it('ends a turn by its terminal frame when the host fails to apply it', async () => {+ const applyEvent = jest.fn((event: ChatEvent) => {+ if (event.type === 'final') {+ throw new Error('apply failed');+ }+ });+ const { chat, stream, transport, onFinish } = setup({+ applyEvent,+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(finalEvent());+ await sent;++ expect(onFinish).toHaveBeenLastCalledWith(+ expect.objectContaining({ isError: true, isDisconnect: false, isSettled: true }),+ );+ await expect(chat.stop()).resolves.toEqual({ status: 'idle' });+ expect(transport.abort).not.toHaveBeenCalled();+ });++ it('reports a lost start stopped once its late stream was stopped on the server', async () => {+ let deliver: ((result: { status: 'stream'; stream: ChatStream }) => void) | undefined;+ const late = createStream({ streamId: 'convo-1', generationCreatedAt: 300 });+ const { chat, transport } = setup();+ transport.sendMessages.mockImplementationOnce(+ () =>+ new Promise((resolve) => {+ deliver = resolve;+ }),+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });+ await sent;++ deliver?.({ status: 'stream', stream: late });+ await flush();++ expect(transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ generationCreatedAt: 300 }),+ );+ await expect(chat.stop()).resolves.toEqual({ status: 'idle' });+ });});describe('ids a turn reports', () => {@@ -1074,6 +2114,23 @@ describe('Chat', () => {expect.objectContaining({ isError: true, message: undefined }),);});++ it('reports no response for a turn stopped before its preparation finished', async () => {+ const earlier: TMessage = { ...placeholder, messageId: 'earlier-1', text: 'Earlier' };+ const { chat, onFinish } = setup({+ state: createState([userMessage, earlier]),+ prepareRequest: jest.fn(() => new Promise<never>(() => undefined)),+ });+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();++ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent.catch(() => undefined);++ expect(onFinish).toHaveBeenCalledWith(+ expect.objectContaining({ isAbort: true, message: undefined }),+ );+ });});});@@ -1637,6 +2694,90 @@ describe('Chat attachments and reported conversations', () => {expect(attachedWith).toEqual(['earlier-1:Earlier', 'earlier-2:Answer', 'user-1:Edited']);});++ /** The rows an Assistants stop answer carries, which replace the list when the run ends. */+ const stored: TMessage[] = [userMessage, { ...placeholder, text: 'Stored' }];+ const storedAnswer = { final: true, conversation: {}, runMessages: stored };++ /** Starts a turn over `state` and stops it with an Assistants answer that carries its rows. */+ const stopWithRunMessages = async (state: ChatState) => {+ const stream = createStream({ streamId: 'convo-1', generationCreatedAt: 100 });+ const { chat, transport } = setup(+ { state, prepareRequest: jest.fn(() => ({ payload, messages: optimistic })) },+ {+ sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })),+ abort: jest.fn(async () => {+ stream.push(finalEvent({ terminalStatus: 'aborted' }));+ return storedAnswer;+ }) as unknown as ChatTransport['abort'],+ },+ );+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ stream.push(stepEvent);+ await flush();+ return { chat, transport, sent };+ };++ const isStored = (messages: TMessage[]) =>+ messages.some((m) => m.messageId === placeholder.messageId && m.text === 'Stored');++ it.each([+ ['over a store that reports writes synchronously', false],+ ['over a structurally shared store', true],+ ])(+ "keeps a row a store subscriber appended inside a stop's run-message merge, %s",+ async (_label, shared) => {+ const state = createStore(shared);+ state.subscribe?.(() => {+ const current = state.messages;+ if (isStored(current) && !current.some((m) => m.messageId === external.messageId)) {+ state.replaceMessages([...current, external]);+ }+ });+ const { chat, sent } = await stopWithRunMessages(state);++ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });+ await sent;++ expect(rows(state.messages)).toEqual([+ 'user-1:Hi',+ 'response-1:Stored',+ 'external-1:External',+ ]);+ },+ );++ it.each([+ ['over a store that reports writes synchronously', false],+ ['over a structurally shared store', true],+ ])(+ "writes nothing more once a store subscriber disposes the chat inside a stop's run-message merge, %s",+ async (_label, shared) => {+ const state = createStore(shared) as ReturnType<typeof createState>;+ let atDispose: { statuses: number; connection: string; rows: string[] } | undefined;+ const { chat, sent } = await stopWithRunMessages(state);+ state.subscribe?.(() => {+ if (!atDispose && isStored(state.messages)) {+ chat.dispose();+ atDispose = {+ statuses: state.statuses.length,+ connection: state.connection,+ rows: rows(state.messages),+ };+ }+ });++ await chat.stop();+ await sent;+ await flush();++ expect(atDispose).toBeDefined();+ expect(state.statuses).toHaveLength(atDispose?.statuses ?? -1);+ expect(state.connection).toBe(atDispose?.connection);+ expect(rows(state.messages)).toEqual(atDispose?.rows);+ },+ );});it('reports an error the generation itself sent on an attachment as terminal', async () => {diff --git a/packages/chat/src/core/__tests__/generations.spec.ts b/packages/chat/src/core/__tests__/generations.spec.tsnew file mode 100644index 0000000000..e81b91a32a--- /dev/null+++ b/packages/chat/src/core/__tests__/generations.spec.ts@@ -0,0 +1,1488 @@+import { StepEvents } from 'librechat-data-provider';+import type { TMessage, TPayload, ChatEvent } from 'librechat-data-provider';+import type {+ ChatInit,+ ChatState,+ ChatStopResult,+ ChatFinishResult,+ ChatPrepareRequest,+ ChatPreparedRequest,+} from '../chat';+import type {+ ChatStream,+ ChatStatus,+ ChatTransport,+ ChatConnection,+ ChatAbortResult,+ ChatSendResult,+} from '../types';+import { Chat } from '../chat';++/**+ * The chat lifecycle as a table: every generation state a chat can be in, crossed with every event+ * that can reach it, and the status, completions and stop target each pair must produce.+ */++type TestStream = ChatStream & { push(event: ChatEvent): void; closed(): boolean };++const createStream = (meta: { streamId?: string; generationCreatedAt?: number } = {}) => {+ const queued: ChatEvent[] = [];+ let wake: (() => void) | undefined;+ let closed = false;+ const stream: TestStream = {+ ...meta,+ push(event) {+ queued.push(event);+ wake?.();+ },+ close() {+ closed = true;+ wake?.();+ },+ closed: () => closed,+ async *[Symbol.asyncIterator]() {+ while (true) {+ while (queued.length > 0) {+ yield queued.shift() as ChatEvent;+ }+ if (closed) {+ return;+ }+ await new Promise<void>((resolve) => {+ wake = resolve;+ });+ }+ },+ };+ return stream;+};++const userMessage: TMessage = {+ messageId: 'user-1',+ conversationId: 'convo-1',+ parentMessageId: null,+ isCreatedByUser: true,+ text: 'Hi',+};++const placeholder: TMessage = {+ messageId: 'response-1',+ conversationId: 'convo-1',+ parentMessageId: 'user-1',+ isCreatedByUser: false,+ text: '',+ content: [],+};++const payload = { endpoint: 'agents', conversationId: 'convo-1', text: 'Hi' } as TPayload;++const stepEvent: ChatEvent = {+ type: 'step',+ data: { event: StepEvents.ON_MESSAGE_DELTA, data: { id: 'step-1', delta: { content: [] } } },+};++const finalEvent = (data: Partial<Extract<ChatEvent, { type: 'final' }>['data']> = {}) =>+ ({+ type: 'final',+ data: { final: true, requestMessage: userMessage, responseMessage: placeholder, ...data },+ }) as ChatEvent;++const dropEvent = { type: 'error', status: 0, data: 'offline' } as ChatEvent;++const networkError = () => Object.assign(new Error('Network Error'), { code: 'ERR_NETWORK' });++const flush = async () => {+ for (let i = 0; i < 5; i++) {+ await new Promise<void>((resolve) => setTimeout(resolve, 0));+ }+};++type Harness = {+ chat: Chat;+ prepare: jest.Mock<ChatPreparedRequest | Promise<ChatPreparedRequest>, [ChatPrepareRequest]>;+ transport: jest.Mocked<Required<ChatTransport>>;+ finishes: ChatFinishResult[];+ /** The stream the chat is attached to, which a confirmed stop ends with an abort frame. */+ stream?: TestStream;+ /** Settles a start or reattachment the state left pending. */+ open?: () => void;+ /** Fails that pending start or reattachment as a request that never got a response. */+ fail?: () => void;+ /** Answers that pending start as one the server already finished. */+ settle?: () => void;+ /** The transport answers a start after it was cancelled, as a request already sent can. */+ answersLate?: boolean;+ outcome?: string;+ /** Whether the turn's own send has settled. */+ turn?: 'pending' | 'settled';+ /** What a second stop answers after the event, which shows what the chat still holds. */+ after?: ChatStopResult['status'];+ /** Answers the stop the event left waiting on the server. */+ answerStop?: () => void;+};++const createHarness = (init: Partial<ChatInit> & { messages?: TMessage[] } = {}): Harness => {+ const { messages: initial = [], ...overrides } = init;+ let messages: TMessage[] = initial;+ const state: ChatState = {+ status: 'ready' as ChatStatus,+ error: undefined,+ connection: 'idle' as ChatConnection,+ get messages() {+ return messages;+ },+ replaceMessages(next) {+ messages = next;+ },+ };+ const finishes: ChatFinishResult[] = [];+ const harness = { finishes } as Harness;+ harness.prepare = jest.fn((_request: ChatPrepareRequest) => ({+ payload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ }));+ harness.transport = {+ sendMessages: jest.fn(),+ reconnectToStream: jest.fn(async () => null),+ abort: jest.fn(async () => {+ harness.stream?.push(finalEvent({ terminalStatus: 'aborted' }));+ return { success: true };+ }),+ resume: jest.fn(async () => ({+ streamId: 'convo-1',+ conversationId: 'convo-1',+ status: 'resuming' as const,+ })),+ } as unknown as jest.Mocked<Required<ChatTransport>>;+ harness.chat = new Chat({+ id: 'convo-1',+ state,+ transport: harness.transport,+ prepareRequest: (...args) => harness.prepare(...args),+ onFinish: (result) => finishes.push(result),+ ...overrides,+ });+ return harness;+};++const attach = (h: Harness, stream: TestStream) => {+ h.stream = stream;+ h.transport.sendMessages.mockResolvedValue({ status: 'stream', stream });+};++const send = (h: Harness) => {+ h.turn = 'pending';+ const settle = () => {+ h.turn = 'settled';+ };+ h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }).then(settle, settle);+};++/** Drives a fresh chat into each generation state. */+const states: Record<string, (h: Harness) => Promise<void>> = {+ /** The host is still preparing the turn; nothing reached the transport. */+ preparing: async (h) => {+ h.prepare.mockImplementation(+ () =>+ new Promise((resolve) => {+ h.open = () =>+ resolve({ payload, messages: [userMessage, placeholder], responseMessageId: 'r-1' });+ }),+ );+ attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 100 }));+ send(h);+ await flush();+ },+ /** The start request is in flight; no stream yet. */+ starting: async (h) => {+ h.transport.sendMessages.mockImplementation(+ (request) =>+ new Promise((resolve, reject) => {+ h.open = () => {+ h.stream = createStream({ streamId: 'convo-1', generationCreatedAt: 100 });+ resolve({ status: 'stream', stream: h.stream });+ };+ h.fail = () => reject(networkError());+ h.settle = () =>+ resolve({ status: 'settled', conversationId: 'convo-1', generationProtocolVersion: 2 });+ request.abortSignal?.addEventListener('abort', () => {+ if (!h.answersLate) {+ reject(new Error('aborted'));+ }+ });+ }),+ );+ send(h);+ await flush();+ },+ /** Streaming a generation this chat started. */+ attached: async (h) => {+ attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 100 }));+ send(h);+ await flush();+ h.stream?.push(stepEvent);+ await flush();+ },+ /** The server finished the turn before the chat attached. */+ settled: async (h) => {+ h.transport.sendMessages.mockResolvedValue({+ status: 'settled',+ conversationId: 'convo-1',+ generationProtocolVersion: 2,+ });+ send(h);+ await flush();+ },+ /** The start was answered with a newer generation, which the chat reattached to. */+ replaced: async (h) => {+ const stream = createStream({ streamId: 'stream-2', generationCreatedAt: 200 });+ h.stream = stream;+ h.transport.sendMessages.mockResolvedValue({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ });+ h.transport.reconnectToStream.mockResolvedValue(stream);+ send(h);+ await flush();+ stream.push(stepEvent);+ await flush();+ },+ /** The generation ended with an abort frame. */+ aborted: async (h) => {+ await states.attached(h);+ h.stream?.push({ type: 'abort', data: {} } as ChatEvent);+ await flush();+ h.stream = undefined;+ },+};++const recordAfter = async (h: Harness) => {+ try {+ h.after = (await h.chat.stop()).status;+ } catch {+ h.after = undefined;+ }+};++const record = (h: Harness, settle: Promise<unknown>) =>+ settle.then(+ (value) => {+ const stopped = value as ChatStopResult | undefined;+ h.outcome = stopped?.status === 'unaddressable' ? 'unaddressable' : 'ok';+ },+ (error: Error) => {+ h.outcome = error.message;+ },+ );++/** Every event that can reach a chat. */+const events: Record<string, (h: Harness) => Promise<void>> = {+ stop: async (h) => {+ await record(h, h.chat.stop());+ await flush();+ },+ streamEnd: async (h) => {+ h.open?.();+ await flush();+ h.stream?.close();+ await flush();+ },+ networkDrop: async (h) => {+ if (h.stream) {+ h.stream.push(dropEvent);+ } else {+ h.fail?.();+ }+ await flush();+ },+ final: async (h) => {+ h.open?.();+ await flush();+ h.stream?.push(finalEvent());+ await flush();+ },+ reconcile: async (h) => {+ h.open?.();+ await flush();+ h.stream?.push(finalEvent({ reconcile: true, reconcileReason: 'terminal_payload_missing' }));+ await flush();+ },+ newTurn: async (h) => {+ const before = h.transport.sendMessages.mock.calls.length;+ h.transport.sendMessages.mockResolvedValue({+ status: 'settled',+ conversationId: 'convo-1',+ generationProtocolVersion: 2,+ });+ await record(h, h.chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] }));+ h.outcome =+ h.transport.sendMessages.mock.calls.length > before ? `sent:${h.outcome}` : h.outcome;+ await flush();+ },+ /** A stop the server confirmed without saving its terminal state, as protocol v2 reports. */+ unsavedStop: async (h) => {+ const reconcile = finalEvent({+ reconcile: true,+ reconcileReason: 'abort_persistence_failed',+ terminalStatus: 'aborted',+ });+ h.transport.abort.mockImplementation(async () => {+ h.stream?.push(reconcile);+ return { success: true, generationProtocolVersion: 2, persistenceFailed: true };+ });+ const opening = !h.stream && !!h.open;+ const stopping = record(h, h.chat.stop());+ await flush();+ if (opening) {+ h.open?.();+ await flush();+ h.stream?.push(reconcile);+ }+ await stopping;+ await flush();+ },+ /** A stop that found the run already finished on its own. */+ settledStop: async (h) => {+ h.transport.abort.mockResolvedValue({+ success: true,+ generationProtocolVersion: 2,+ settled: true,+ terminalStatus: 'complete',+ });+ await events.stop(h);+ },+ /** A stop the server answers 404: the generation finished and was deleted before it arrived. */+ goneStop: async (h) => {+ h.transport.abort.mockRejectedValue(+ Object.assign(new Error('Not found'), { response: { status: 404 } }),+ );+ await events.stop(h);+ },+ dispose: async (h) => {+ h.chat.dispose();+ await flush();+ },+ /** A stop whose server answer, or the start it raced, arrives after it was asked. */+ lateAnswer: async (h) => {+ h.answersLate = true;+ h.transport.abort.mockImplementation(+ () =>+ new Promise((resolve) => {+ h.answerStop = () => {+ h.stream?.push(finalEvent({ terminalStatus: 'aborted' }));+ resolve({ success: true });+ };+ }),+ );+ const stopping = record(h, h.chat.stop());+ await flush();+ h.open?.();+ await flush();+ h.answerStop?.();+ await stopping;+ await flush();+ h.answerStop?.();+ await flush();+ await recordAfter(h);+ },+ /** A late answer to a cancelled start that says the server already finished it. */+ lateSettled: async (h) => {+ h.answersLate = true;+ const stopping = record(h, h.chat.stop());+ await flush();+ h.settle?.();+ await stopping;+ await flush();+ await recordAfter(h);+ },+ /** The chat is disposed while a stop waits on a server that never answers. */+ disposeDuringStop: async (h) => {+ h.transport.abort.mockImplementation(() => new Promise(() => undefined));+ const stopping = record(h, h.chat.stop());+ await flush();+ h.chat.dispose();+ await stopping;+ await flush();+ },+};++type Expected = {+ status: ChatStatus;+ connection?: ChatConnection;+ /** How many times `onFinish` ran, over the state and the event together. */+ finishes: number;+ /** Flags of the last `onFinish`. */+ last?: Partial<+ Pick<ChatFinishResult, 'isAbort' | 'isDisconnect' | 'isError' | 'isSettled' | 'reconcileReason'>+ >;+ /** What `transport.abort` was asked to stop, or `null` when it was not called. */+ abort?: { streamId?: string; generationCreatedAt?: number } | null;+ /** The event's own result: `ok`, a rejection message fragment, or `sent:` for a new turn. */+ outcome?: string;+ turn?: 'pending' | 'settled';+ after?: ChatStopResult['status'];+ /** How many starts reached the transport. */+ starts?: number;+};++const NONE = null;+const done = { isAbort: false, isDisconnect: false, isError: false, isSettled: false };+const aborted = { ...done, isAbort: true };+const dropped = { ...done, isError: true, isDisconnect: true };+const settled = { ...done, isSettled: true };+/** A confirmed stop whose abort frame never arrived, which the host reloads. */+const stoppedUnframed = { ...aborted, isSettled: true };+const unsaved = {+ ...aborted,+ isSettled: true,+ reconcileReason: 'abort_persistence_failed' as const,+};++const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [+ ['starting', 'final', { status: 'ready', finishes: 1, last: done, abort: NONE }],+ ['starting', 'newTurn', { status: 'submitted', finishes: 0, outcome: 'in flight' }],+ [+ 'starting',+ 'stop',+ { status: 'error', finishes: 1, last: dropped, abort: NONE, outcome: 'unaddressable' },+ ],++ [+ 'attached',+ 'stop',+ {+ status: 'ready',+ finishes: 1,+ last: aborted,+ abort: { streamId: 'convo-1', generationCreatedAt: 100 },+ },+ ],+ [+ 'attached',+ 'streamEnd',+ { status: 'error', connection: 'idle', finishes: 1, last: dropped, abort: NONE },+ ],+ [+ 'attached',+ 'networkDrop',+ { status: 'error', connection: 'idle', finishes: 1, last: dropped, abort: NONE },+ ],+ ['attached', 'final', { status: 'ready', connection: 'idle', finishes: 1, last: done }],+ ['attached', 'reconcile', { status: 'ready', finishes: 1, last: settled }],+ ['attached', 'newTurn', { status: 'streaming', finishes: 0, outcome: 'in flight' }],++ ['settled', 'stop', { status: 'ready', finishes: 1, last: settled, abort: NONE, outcome: 'ok' }],+ ['settled', 'newTurn', { status: 'ready', finishes: 2, outcome: 'sent:ok' }],++ [+ 'replaced',+ 'stop',+ {+ status: 'ready',+ finishes: 1,+ last: aborted,+ abort: { streamId: 'stream-2', generationCreatedAt: 200 },+ },+ ],+ ['replaced', 'networkDrop', { status: 'error', finishes: 1, last: dropped }],+ ['replaced', 'final', { status: 'ready', finishes: 1, last: done }],+ ['replaced', 'newTurn', { status: 'streaming', finishes: 0, outcome: 'in flight' }],++ ['aborted', 'stop', { status: 'ready', finishes: 1, last: aborted, abort: NONE, outcome: 'ok' }],+ ['aborted', 'newTurn', { status: 'ready', finishes: 2, outcome: 'sent:ok' }],++ /** Network failures before a stream, and the stop that follows a drop or a restore. */+ ['starting', 'streamEnd', { status: 'error', finishes: 1, last: dropped, abort: NONE }],+ ['starting', 'networkDrop', { status: 'error', finishes: 1, last: dropped, abort: NONE }],+ ['replaced', 'streamEnd', { status: 'error', finishes: 1, last: dropped }],++ /** Stops the server answered as unsaved or as already settled; neither is a plain abort. */+ [+ 'attached',+ 'unsavedStop',+ {+ status: 'ready',+ finishes: 1,+ last: unsaved,+ abort: { streamId: 'convo-1', generationCreatedAt: 100 },+ outcome: 'ok',+ },+ ],+];++const live = { streamId: 'convo-1', generationCreatedAt: 100 };++/**+ * Dispose, stop and a late server answer, across every phase a turn can be in: before its start is+ * sent, while the start is pending, live, paused, and restored from a status read. Every awaiter+ * settles, and nothing the chat no longer holds survives as a stop target.+ */+const teardown: Array<[keyof typeof states, keyof typeof events, Expected]> = [+ [+ 'preparing',+ 'dispose',+ { status: 'ready', connection: 'idle', finishes: 0, turn: 'settled', abort: NONE, starts: 0 },+ ],+ [+ 'preparing',+ 'stop',+ {+ status: 'ready',+ finishes: 1,+ last: aborted,+ turn: 'settled',+ abort: NONE,+ outcome: 'ok',+ starts: 0,+ },+ ],+ [+ 'preparing',+ 'lateAnswer',+ {+ status: 'ready',+ finishes: 1,+ last: aborted,+ turn: 'settled',+ abort: NONE,+ outcome: 'ok',+ after: 'idle',+ starts: 0,+ },+ ],+ [+ 'preparing',+ 'disposeDuringStop',+ { status: 'ready', finishes: 1, turn: 'settled', abort: NONE, outcome: 'ok', starts: 0 },+ ],++ [+ 'starting',+ 'dispose',+ { status: 'submitted', connection: 'idle', finishes: 0, turn: 'settled', abort: NONE },+ ],+ [+ 'starting',+ 'lateAnswer',+ {+ status: 'ready',+ finishes: 1,+ last: dropped,+ turn: 'settled',+ abort: live,+ outcome: 'unaddressable',+ after: 'idle',+ },+ ],+ [+ 'starting',+ 'lateSettled',+ {+ status: 'ready',+ finishes: 1,+ last: dropped,+ turn: 'settled',+ abort: NONE,+ outcome: 'unaddressable',+ after: 'idle',+ },+ ],+ [+ 'starting',+ 'disposeDuringStop',+ { status: 'error', finishes: 1, turn: 'settled', abort: NONE, outcome: 'unaddressable' },+ ],++ [+ 'attached',+ 'dispose',+ { status: 'streaming', connection: 'idle', finishes: 0, turn: 'settled', abort: NONE },+ ],+ [+ 'attached',+ 'lateAnswer',+ {+ status: 'ready',+ connection: 'idle',+ finishes: 1,+ last: aborted,+ turn: 'settled',+ abort: live,+ outcome: 'ok',+ after: 'idle',+ },+ ],+ [+ 'attached',+ 'disposeDuringStop',+ {+ status: 'streaming',+ connection: 'idle',+ finishes: 0,+ turn: 'settled',+ abort: live,+ outcome: 'disposed',+ },+ ],+];++/** A stop that finds the generation already gone ends whatever the chat still held for it. */+const gone: Array<[keyof typeof states, keyof typeof events, Expected]> = [+ [+ 'attached',+ 'goneStop',+ {+ status: 'ready',+ connection: 'idle',+ finishes: 1,+ last: settled,+ abort: live,+ outcome: 'ok',+ after: undefined,+ },+ ],+];++describe('Chat teardown', () => {+ it.each([...teardown, ...gone])('%s + %s', async (state, event, expected) => {+ const h = createHarness();+ await states[state](h);+ await events[event](h);++ expect(h.chat.status).toBe(expected.status);+ if (expected.connection) {+ expect(h.chat.connection).toBe(expected.connection);+ }+ expect(h.finishes).toHaveLength(expected.finishes);+ if (expected.last) {+ expect(h.finishes[h.finishes.length - 1]).toMatchObject(expected.last);+ }+ if (expected.abort === null) {+ expect(h.transport.abort).not.toHaveBeenCalled();+ } else if (expected.abort) {+ expect(h.transport.abort).toHaveBeenCalledTimes(1);+ expect(h.transport.abort).toHaveBeenCalledWith(expect.objectContaining(expected.abort));+ }+ if (expected.outcome !== undefined) {+ expect(h.outcome).toContain(expected.outcome);+ }+ if (expected.turn) {+ expect(h.turn).toBe(expected.turn);+ }+ if (expected.after) {+ expect(h.after).toBe(expected.after);+ }+ if (expected.starts !== undefined) {+ expect(h.transport.sendMessages).toHaveBeenCalledTimes(expected.starts);+ }+ });+});++describe('Chat lifecycle', () => {+ it.each(table)('%s + %s', async (state, event, expected) => {+ const h = createHarness();+ await states[state](h);+ await events[event](h);++ expect(h.chat.status).toBe(expected.status);+ if (expected.connection) {+ expect(h.chat.connection).toBe(expected.connection);+ }+ expect(h.finishes).toHaveLength(expected.finishes);+ if (expected.last) {+ expect(h.finishes[h.finishes.length - 1]).toMatchObject(expected.last);+ }+ if (expected.abort === null) {+ expect(h.transport.abort).not.toHaveBeenCalled();+ } else if (expected.abort) {+ expect(h.transport.abort).toHaveBeenCalledTimes(1);+ expect(h.transport.abort).toHaveBeenCalledWith(expect.objectContaining(expected.abort));+ }+ if (expected.outcome !== undefined) {+ expect(h.outcome).toContain(expected.outcome);+ }+ });+});++/**+ * The invariants every generation marker keeps, crossed with the states that hold one:+ * (1) an async continuation acts only on the generation it captured;+ * (2) a "may still be running" marker survives until the server answers for it;+ * (3) a disposed chat reaches no transport method;+ * (4) a generation record carries the response its source named, or counts it unknown.+ */+const disposedCalls: Record<string, (h: Harness) => Promise<unknown>> = {+ stop: (h) => h.chat.stop(),+ sendMessage: (h) => h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }),+};++const transportCalls = (h: Harness) =>+ h.transport.sendMessages.mock.calls.length ++ h.transport.reconnectToStream.mock.calls.length ++ h.transport.abort.mock.calls.length ++ h.transport.resume.mock.calls.length;++const disposedTable = Object.keys(states).flatMap((state) =>+ Object.keys(disposedCalls).map((call) => [state, call] as const),+);++describe('Chat invariants', () => {+ it.each(disposedTable)('(3) %s, disposed, then %s reaches no transport', async (state, call) => {+ const h = createHarness();+ await states[state](h);+ h.chat.dispose();+ await flush();+ const before = transportCalls(h);+ let settled = false;+ disposedCalls[call](h).then(+ () => (settled = true),+ () => (settled = true),+ );+ await flush();++ expect(transportCalls(h)).toBe(before);+ expect(settled).toBe(true);+ });++ it.each([+ [+ 'a replacement',+ (h: Harness) => {+ h.transport.sendMessages.mockResolvedValue({+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'convo-1',+ generationCreatedAt: 300,+ generationProtocolVersion: 2,+ });+ send(h);+ },+ ],+ ])(+ '(1) a stop of %s leaves the other generation its reconnect found running',+ async (_label, start) => {+ const h = createHarness();+ let answerStop: (() => void) | undefined;+ h.transport.abort.mockImplementation(+ () => new Promise((resolve) => (answerStop = () => resolve({ success: true }))),+ );+ const other = createStream({ streamId: 'convo-1', generationCreatedAt: 400 });+ let openOther: (() => void) | undefined;+ h.transport.reconnectToStream.mockImplementation(+ () => new Promise((resolve) => (openOther = () => resolve(other))),+ );+ start(h);+ await flush();+ const first = h.chat.stop();+ await flush();+ openOther?.();+ await flush();+ answerStop?.();+ await first;+ other.push(stepEvent);+ await flush();++ expect(other.closed()).toBe(false);+ expect(h.chat.status).toBe('streaming');+ h.transport.abort.mockResolvedValueOnce({ success: true });+ const second = h.chat.stop();+ await flush();+ expect(h.transport.abort).toHaveBeenCalledTimes(2);+ expect(h.transport.abort).toHaveBeenLastCalledWith(+ expect.objectContaining({ generationCreatedAt: 400 }),+ );+ other.push(finalEvent({ terminalStatus: 'aborted' }));+ await second;+ },+ );++ it.each([+ ['settled', { status: 'settled', conversationId: 'convo-1', generationProtocolVersion: 2 }],+ [+ 'replaced',+ {+ status: 'replaced',+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ },+ ],+ ])(+ "(2) a cancelled start the server answers late as %s is no longer the caller's",+ async (_label, late) => {+ const h = createHarness();+ let answer: (() => void) | undefined;+ h.transport.sendMessages.mockImplementation(+ () => new Promise((resolve) => (answer = () => resolve(late as never))),+ );+ send(h);+ await flush();+ await expect(h.chat.stop()).resolves.toEqual({ status: 'unaddressable' });+ answer?.();+ await flush();++ await expect(h.chat.stop()).resolves.toEqual({ status: 'idle' });+ expect(h.transport.abort).not.toHaveBeenCalled();+ expect(h.transport.reconnectToStream).not.toHaveBeenCalled();+ },+ );+});++/** Where a host callback or transport method can throw once a request owns the chat. */+type Fault = { fault: boolean };++const throwing = (f: Fault, what: string) => {+ if (f.fault) {+ f.fault = false;+ throw new Error(`${what} failed`);+ }+};++const settles = async (pending: Promise<unknown>) => {+ let done = false;+ pending.then(+ () => (done = true),+ () => (done = true),+ );+ await flush();+ return done;+};++const freeAfter = async (h: Harness) => {+ attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 900 }));+ const next = h.chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] });+ next.then(+ () => undefined,+ () => undefined,+ );+ await flush();+ return h.chat.status === 'submitted' || h.chat.status === 'streaming';+};++describe('Chat exception safety', () => {+ it.each([+ ['prepareRequest throws', 'prepare-sync'],+ ['prepareRequest rejects', 'prepare-async'],+ ['transport.sendMessages throws', 'send'],+ ])('(5) a start whose %s settles and frees the chat', async (_label, where) => {+ const f: Fault = { fault: true };+ const h = createHarness({+ prepareRequest: () => {+ if (where === 'prepare-sync') {+ throwing(f, 'prepare');+ }+ if (where === 'prepare-async' && f.fault) {+ f.fault = false;+ return Promise.reject(new Error('prepare failed')) as never;+ }+ return { payload, messages: [userMessage, placeholder], responseMessageId: 'response-1' };+ },+ });+ if (where === 'send') {+ h.transport.sendMessages.mockImplementationOnce(() => {+ throw new Error('send failed');+ });+ }++ expect(await settles(h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }))).toBe(true);+ expect(await freeAfter(h)).toBe(true);+ });++ it('(5) a stop whose transport.abort throws leaves the stream attached and a later stop sends anew', async () => {+ const h = createHarness();+ await states.attached(h);+ h.transport.abort.mockImplementationOnce(() => {+ throw new Error('abort failed');+ });++ await expect(h.chat.stop()).rejects.toThrow('abort failed');+ expect(h.chat.connection).toBe('live');+ await h.chat.stop();+ expect(h.transport.abort).toHaveBeenCalledTimes(2);+ });+});++describe('Chat stops the server answers as already settled', () => {+ it('(1) an attached stop answered as settled ends the turn without its terminal frame', async () => {+ const h = createHarness();+ await states.attached(h);+ h.transport.abort.mockResolvedValueOnce({+ success: false,+ settled: true,+ terminalStatus: 'complete',+ generationProtocolVersion: 2,+ });++ expect(await settles(h.chat.stop())).toBe(true);+ expect(h.stream?.closed()).toBe(true);+ expect(h.chat.status).toBe('ready');+ expect(h.finishes[h.finishes.length - 1]).toMatchObject({ isSettled: true, isAbort: false });+ });+});++describe('Chat final frames', () => {+ const complete: TMessage = { ...placeholder, messageId: 'response-new', text: 'Whole' };++ it.each([+ [+ 'a partial row it does not hold, which it leaves out',+ { messageId: 'response-new', text: 'Part' },+ false,+ ],+ ['a complete row it does not hold, which it appends', complete, true],+ ])('(6) a final frame with %s', async (_label, responseMessage, appended) => {+ const h = createHarness();+ await states.attached(h);+ h.stream?.push(finalEvent({ responseMessage: responseMessage as TMessage }));+ await flush();++ expect(h.chat.messages.some((message) => message.messageId === 'response-new')).toBe(appended);+ expect(h.chat.messages.every((message) => typeof message.isCreatedByUser === 'boolean')).toBe(+ true,+ );+ });++ it('(6) a final frame with a partial row it holds merges the fields it carries', async () => {+ const h = createHarness();+ await states.attached(h);+ h.stream?.push(+ finalEvent({ responseMessage: { messageId: 'response-1', text: 'Done' } as TMessage }),+ );+ await flush();++ expect(h.chat.messages.find((message) => message.messageId === 'response-1')).toMatchObject({+ text: 'Done',+ conversationId: 'convo-1',+ isCreatedByUser: false,+ });+ });+});++const createdUnder = 'convo-9';+describe('Chat late answers and lost starts', () => {+ it.each([+ ['settled', { status: 'settled', conversationId: createdUnder, generationProtocolVersion: 2 }],+ [+ 'replaced',+ {+ status: 'replaced',+ conversationId: createdUnder,+ streamId: 'stream-2',+ generationCreatedAt: 200,+ generationProtocolVersion: 2,+ },+ ],+ ])(+ '(7) a cancelled first turn answered late as %s carries the conversation into the next turn',+ async (_label, late) => {+ const h = createHarness({+ id: 'new',+ prepareRequest: () => ({+ payload: { ...payload, conversationId: null } as unknown as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ }),+ });+ let answer: (() => void) | undefined;+ h.transport.sendMessages.mockImplementationOnce(+ () => new Promise((resolve) => (answer = () => resolve(late as never))),+ );+ send(h);+ await flush();+ await h.chat.stop();+ answer?.();+ await flush();++ attach(h, createStream({ streamId: createdUnder, generationCreatedAt: 900 }));+ send(h);+ await flush();+ expect(h.transport.sendMessages).toHaveBeenLastCalledWith(+ expect.objectContaining({ chatId: createdUnder }),+ );+ },+ );+});++describe('Chat stops while a lost start is owed', () => {+ it('(2) an Assistants stop answer without a conversation still resolves the stop', async () => {+ const h = createHarness();+ await states.attached(h);+ h.transport.abort.mockResolvedValueOnce({+ final: true,+ runMessages: [],+ } as unknown as ChatAbortResult);++ await expect(h.chat.stop()).resolves.toEqual({ status: 'stopped' });+ });+});++/**+ * Every way a stop ends a request, and whether the host is asked to reload (`isSettled`). The rule:+ * a stop the server confirmed reloads whenever no terminal frame delivered what it saved; a frame+ * that did deliver it, a stop the server never answered, and a stop it refused do not.+ */+type StopExit = {+ /** The last finish, or `null` when the exit must not finish the turn. */+ last: Partial<+ Pick<ChatFinishResult, 'isAbort' | 'isDisconnect' | 'isError' | 'isSettled'>+ > | null;+ /** The stop's own result: `ok`, `unaddressable`, or a rejection message fragment. */+ outcome: string;+};++const stopExits: Array<[string, (h: Harness) => Promise<void>, StopExit]> = [+ [+ 'live: the abort frame delivers the saved response',+ async (h) => {+ await states.attached(h);+ await events.stop(h);+ },+ { last: aborted, outcome: 'ok' },+ ],+ [+ 'live: the stream drops before the abort frame',+ async (h) => {+ await states.attached(h);+ h.transport.abort.mockImplementation(async () => {+ h.stream?.push(dropEvent);+ return { success: true };+ });+ await events.stop(h);+ },+ { last: stoppedUnframed, outcome: 'ok' },+ ],+ [+ 'live: the server could not save the stop, and its reconcile frame says so',+ async (h) => {+ await states.attached(h);+ await events.unsavedStop(h);+ },+ { last: unsaved, outcome: 'ok' },+ ],+ [+ 'live: the run had already settled on its own',+ async (h) => {+ await states.attached(h);+ await events.settledStop(h);+ },+ { last: settled, outcome: 'ok' },+ ],+ [+ 'live: the server no longer knows the run (404)',+ async (h) => {+ await states.attached(h);+ await events.goneStop(h);+ },+ { last: settled, outcome: 'ok' },+ ],+ [+ 'never answered: the start lost its response, so the stop cannot name it',+ async (h) => {+ await states.starting(h);+ await events.stop(h);+ },+ { last: dropped, outcome: 'unaddressable' },+ ],+ [+ 'never sent: the turn is stopped while the host still prepares it',+ async (h) => {+ await states.preparing(h);+ await events.stop(h);+ h.open?.();+ await flush();+ },+ { last: aborted, outcome: 'ok' },+ ],+ [+ 'network drop: the stop request itself fails, so the run is left streaming',+ async (h) => {+ await states.attached(h);+ h.transport.abort.mockRejectedValue(networkError());+ await events.stop(h);+ },+ { last: null, outcome: 'Network Error' },+ ],+ [+ 'refused: the server answers the stop without stopping the run',+ async (h) => {+ await states.attached(h);+ h.transport.abort.mockResolvedValue({ success: false, error: 'The stop was refused' });+ await events.stop(h);+ },+ { last: null, outcome: 'The stop was refused' },+ ],+];++describe('Chat stop exits and the reload signal', () => {+ it.each(stopExits)('%s', async (_exit, drive, expected) => {+ const h = createHarness();+ await drive(h);++ expect(h.outcome).toContain(expected.outcome);+ if (expected.last === null) {+ expect(h.finishes).toHaveLength(0);+ return;+ }+ expect(h.finishes[h.finishes.length - 1]).toMatchObject(expected.last);+ });+});++/**+ * Table 3: every place the core notifies subscribers. The rule: a request installs its ownership+ * (the active record, or the pause it is answering) before any notify, and an entry point that+ * notifies before it owns the chat rechecks afterwards, so a subscriber that starts a turn is+ * neither overwritten nor run twice.+ */+describe('Chat notify ordering and request ownership', () => {+ const startOnNotify = (h: Harness, when: () => boolean) => {+ const attempt: { started?: boolean; sent?: Promise<void>; error?: string } = {};+ const unsubscribe = h.chat.subscribe(() => {+ if (attempt.started || !when()) {+ return;+ }+ /** Set before the call, since the turn it starts notifies of its own status first. */+ attempt.started = true;+ attempt.sent = h.chat.sendMessage({ parts: [{ type: 'text', text: 'Queued' }] });+ attempt.sent.catch((error: Error) => {+ attempt.error = error.message;+ });+ });+ return { attempt, unsubscribe };+ };++ it('a request owns the chat before it notifies that it was submitted', async () => {+ const h = createHarness();+ attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 100 }));+ const { attempt, unsubscribe } = startOnNotify(h, () => h.chat.status === 'submitted');+ send(h);+ await flush();+ unsubscribe();++ expect(attempt.error).toContain('already in flight');+ expect(h.transport.sendMessages).toHaveBeenCalledTimes(1);+ });++ it('a streamed frame notifies while the request still owns the chat', async () => {+ const h = createHarness();+ attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 100 }));+ send(h);+ await flush();+ const { attempt, unsubscribe } = startOnNotify(h, () => h.chat.status === 'streaming');+ h.stream?.push(stepEvent);+ await flush();+ unsubscribe();++ expect(attempt.error).toContain('already in flight');+ expect(h.transport.sendMessages).toHaveBeenCalledTimes(1);+ });++ it('a turn that ends notifies after it released the chat, so the next turn owns it', async () => {+ const h = createHarness();+ await states.attached(h);+ const next = createStream({ streamId: 'convo-1', generationCreatedAt: 300 });+ const { attempt, unsubscribe } = startOnNotify(h, () => h.chat.status === 'ready');+ h.transport.sendMessages.mockResolvedValueOnce({ status: 'stream', stream: next });+ h.stream?.push(finalEvent());+ await flush();+ unsubscribe();++ expect(attempt.error).toBeUndefined();+ expect(h.chat.status).toBe('submitted');+ expect(h.transport.sendMessages).toHaveBeenCalledTimes(2);+ });++ it('a dispose notifies after the chat is disposed, so a turn a subscriber starts is refused', async () => {+ const h = createHarness();+ await states.attached(h);+ const { attempt, unsubscribe } = startOnNotify(h, () => true);+ h.chat.dispose();+ await flush();+ unsubscribe();++ expect(attempt.error ?? 'none').not.toBe('none');+ expect(h.transport.sendMessages).toHaveBeenCalledTimes(1);+ });+});++const learns: Array<[string, (h: Harness) => Promise<void>]> = [+ [+ 'a sync frame',+ async (h) => {+ const stream = createStream({ streamId: createdUnder, generationCreatedAt: 100 });+ attach(h, stream);+ send(h);+ await flush();+ stream.push({+ type: 'sync',+ data: { conversationId: createdUnder, responseMessage: placeholder },+ } as ChatEvent);+ stream.push(finalEvent());+ await flush();+ },+ ],+ [+ 'a created frame',+ async (h) => {+ const stream = createStream({ streamId: createdUnder, generationCreatedAt: 100 });+ attach(h, stream);+ send(h);+ await flush();+ stream.push({+ type: 'created',+ data: { message: { ...userMessage, conversationId: createdUnder }, created: true },+ } as ChatEvent);+ stream.push(finalEvent());+ await flush();+ },+ ],+ [+ 'a settled start',+ async (h) => {+ h.transport.sendMessages.mockResolvedValueOnce({+ status: 'settled',+ conversationId: createdUnder,+ generationProtocolVersion: 2,+ });+ send(h);+ await flush();+ },+ ],+];++describe('Chat conversation identity', () => {+ it.each(learns)(+ '(7) after %s names the conversation, later turns and stops use it',+ async (_label, learn) => {+ const prepared: string[] = [];+ const h = createHarness({+ id: 'new',+ prepareRequest: (request) => {+ prepared.push(request.chatId);+ return {+ payload: { ...payload, conversationId: null } as unknown as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ };+ },+ });+ await learn(h);++ const next = createStream({ streamId: createdUnder, generationCreatedAt: 700 });+ attach(h, next);+ send(h);+ await flush();+ expect(prepared[prepared.length - 1]).toBe(createdUnder);+ expect(h.transport.sendMessages).toHaveBeenLastCalledWith(+ expect.objectContaining({ chatId: createdUnder }),+ );+ await h.chat.stop();+ expect(h.transport.abort).toHaveBeenLastCalledWith(+ expect.objectContaining({ chatId: createdUnder }),+ );+ },+ );+});++describe('Chat identity every frame carries', () => {+ const ids = { conversationId: createdUnder, responseMessageId: 'response-9' };+ const frames: Array<[string, ChatEvent, { response?: boolean; conversation?: boolean }]> = [+ [+ 'activity_label',+ { type: 'activity_label', data: { index: 0, part: {}, ...ids } } as unknown as ChatEvent,+ { response: true, conversation: true },+ ],+ [+ 'reasoning_label',+ { type: 'reasoning_label', data: { index: 0, ...ids } } as unknown as ChatEvent,+ { response: true, conversation: true },+ ],+ [+ 'steer_applied',+ {+ type: 'steer_applied',+ data: { steerId: 's', index: 0, part: {}, ...ids },+ } as unknown as ChatEvent,+ { response: true, conversation: true },+ ],+ [+ 'content',+ {+ type: 'content',+ data: {+ index: 0,+ type: 'text',+ text: 'x',+ messageId: 'response-9',+ conversationId: createdUnder,+ },+ } as unknown as ChatEvent,+ { response: true, conversation: true },+ ],+ [+ 'text',+ { type: 'text', data: { text: 'x', messageId: 'response-9' } } as unknown as ChatEvent,+ { response: true },+ ],+ [+ 'title',+ {+ type: 'title',+ data: { event: 'title', data: { conversationId: createdUnder, title: 'T' } },+ } as ChatEvent,+ { conversation: true },+ ],+ [+ 'steer_updated',+ { type: 'steer_updated', data: { conversationId: createdUnder } } as unknown as ChatEvent,+ { conversation: true },+ ],+ ];++ it.each(frames)(+ '(4)(7) the %s frame on a live turn names what it carries',+ async (_label, frame, names) => {+ const named: TMessage = { ...placeholder, messageId: 'response-9', text: 'Named' };+ const h = createHarness({+ id: 'new',+ messages: [userMessage, named, { ...placeholder, messageId: 'other' }],+ prepareRequest: () => ({+ payload: { ...payload, conversationId: null } as unknown as TPayload,+ }),+ });+ const stream = createStream({ streamId: createdUnder, generationCreatedAt: 700 });+ attach(h, stream);+ send(h);+ await flush();+ stream.push(frame);+ await flush();+ stream.push({ type: 'error', data: 'failed' } as ChatEvent);+ await flush();++ const last = h.finishes[h.finishes.length - 1];+ if (names.response) {+ expect(last).toMatchObject({ isResponseUnknown: false });+ expect(last.message?.messageId).toBe('response-9');+ }+ if (names.conversation) {+ attach(h, createStream({ streamId: createdUnder, generationCreatedAt: 800 }));+ send(h);+ await flush();+ expect(h.transport.sendMessages).toHaveBeenLastCalledWith(+ expect.objectContaining({ chatId: createdUnder }),+ );+ }+ },+ );+});++describe('Chat disposed while a confirmed stop ends its request', () => {+ it.each([0, 1, 2, 3, 4, 6, 8, 12])(+ '(3) a chat disposed %i microtasks into the Assistants answer to a stop of a live turn writes no state',+ async (ticks) => {+ const h = createHarness();+ await states.attached(h);+ let answerStop: (() => void) | undefined;+ h.transport.abort.mockImplementation(+ () =>+ new Promise((resolve) => {+ answerStop = () =>+ resolve({+ final: true,+ conversation: {},+ runMessages: [userMessage],+ } as unknown as ChatAbortResult);+ }),+ );+ let stopped = false;+ h.chat.stop().then(+ () => {+ stopped = true;+ },+ () => {+ stopped = true;+ },+ );+ await flush();++ answerStop?.();+ for (let i = 0; i < ticks; i++) {+ await Promise.resolve();+ }+ const { status, error, messages } = h.chat;+ h.chat.dispose();+ await flush();++ expect(stopped).toBe(true);+ expect(h.chat.status).toBe(status);+ expect(h.chat.error).toBe(error);+ expect(h.chat.messages).toBe(messages);+ },+ );+});++describe('Chat stop answers for a start answered late', () => {+ it('(7) a late stream under `new` stopped by its own stop answer names the conversation the next turn uses', async () => {+ const h = createHarness({+ id: 'new',+ prepareRequest: () => ({+ payload: { ...payload, conversationId: null } as unknown as TPayload,+ messages: [userMessage, placeholder],+ responseMessageId: 'response-1',+ }),+ });+ let answer: ((result: ChatSendResult) => void) | undefined;+ h.transport.sendMessages.mockImplementationOnce(+ () =>+ new Promise<ChatSendResult>((resolve) => {+ answer = resolve;+ }),+ );+ const first = h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });+ await flush();+ expect((await h.chat.stop()).status).toBe('unaddressable');+ await first;+ h.transport.abort.mockResolvedValueOnce({ success: true, aborted: createdUnder });+ answer?.({ status: 'stream', stream: createStream({ streamId: createdUnder }) });+ await flush();++ expect(h.chat.conversationId).toBe(createdUnder);+ expect(h.chat.status).toBe('ready');+ });+});++describe('Chat replacements and the notifications their rollback sends', () => {+ it('a stop a subscriber sends while the replaced turn is undone reaches the replacement', async () => {+ const h = createHarness();+ h.transport.sendMessages.mockResolvedValueOnce({+ status: 'replaced',+ generationProtocolVersion: 2,+ conversationId: 'convo-1',+ streamId: 'stream-2',+ generationCreatedAt: 200,+ });+ h.transport.reconnectToStream.mockImplementationOnce(() => new Promise(() => undefined));+ h.transport.abort.mockResolvedValueOnce({ success: true, aborted: 'stream-2' });+ let stopping: Promise<ChatStopResult> | undefined;+ let written = false;+ const unsubscribe = h.chat.subscribe(() => {+ written ||= h.chat.messages.length > 0;+ if (!stopping && written && h.chat.messages.length === 0) {+ stopping = h.chat.stop();+ }+ });+ send(h);+ await flush();+ unsubscribe();++ expect(stopping).toBeDefined();+ expect((await stopping)?.status).toBe('stopped');+ expect(h.transport.abort).toHaveBeenCalledWith(+ expect.objectContaining({ streamId: 'stream-2', generationCreatedAt: 200 }),+ );+ });+});diff --git a/packages/chat/src/core/chat.ts b/packages/chat/src/core/chat.tsindex 1df4f71810..ceb9dd6c2a 100644--- a/packages/chat/src/core/chat.ts+++ b/packages/chat/src/core/chat.ts@@ -4,6 +4,7 @@ import type {TMessage,ChatEvent,UITextPart,+ TPendingSteer,ChatFinalFrame,ChatErrorData,UIMessageMetadata,@@ -16,6 +17,9 @@ import type {ChatConnection,ChatRequestOptions,ChatSendResult,+ ChatAbortResult,+ ChatAbortRequest,+ ChatStreamAbortResult,ChatTransportError,} from './types';import { isRetryableNetworkError } from './resumable/start';@@ -103,10 +107,31 @@ export type ChatFinishResult = {* frames or payload named, so a turn under `new` reports the conversation the server created.*/conversationId?: string;- /** Why a settled turn's final frame carried no messages. */+ /**+ * Why a settled turn's final frame carried no messages. `abort_persistence_failed` means the+ * stop was not saved, so work queued behind it must not run.+ */reconcileReason?: ChatFinalFrame['reconcileReason'];};+/**+ * What a stop did. `stopped` ended the turn, `idle` found nothing to stop, and `unaddressable`+ * means a generation may still run that this chat saw no frame for (a start whose response was+ * lost, or a turn under `new` before its sync frame), so the caller stops it on its own abort path.+ */+export type ChatStopResult =+ | {+ status: 'stopped';+ /** The conversation the server stopped, authoritative while the chat still holds `new`. */+ conversationId?: string;+ /** Steers the run never injected, which the host restores as queued turns. */+ pendingSteers?: TPendingSteer[];+ }+ | { status: 'idle' }+ | { status: 'unaddressable' };++const unaddressable: ChatStopResult = { status: 'unaddressable' };+export type ChatInit = {/** The conversation id, or `new` before the server created one. */id: string;@@ -114,7 +139,7 @@ export type ChatInit = {transport: ChatTransport;/*** Builds the request body, and the optimistic messages, for a turn. AI SDK:- * `prepareSendMessagesRequest`.+ * `prepareSendMessagesRequest`. The payload's endpoint is what a stop addresses.*/prepareRequest(request: ChatPrepareRequest): ChatPreparedRequest | Promise<ChatPreparedRequest>;/**@@ -144,8 +169,12 @@ type Outcome = {| { kind: 'error'; error: Error; disconnect: boolean });-/** The response a turn produces, as the frames of its generation name it. */+/**+ * A generation on the server as this chat knows it. It outlives the requests attached to it, so a+ * stop and the request it ends read and write one record instead of copying its fields across.+ */type Generation = {+ endpoint?: string;/** The conversation the payload, the server's answer or a frame named. */conversationId?: string;/** The response this generation produces: the placeholder, then the one a frame names. */@@ -155,6 +184,23 @@ type Generation = {* response yet.*/responseUnknown?: boolean;+ /** Set once the server confirmed a stop, so a stream that drops instead of ending aborts. */+ stopped?: boolean;+ /** The terminal status a stop answer reported for a run that had already ended on its own. */+ settledAs?: ChatStreamAbortResult['terminalStatus'];+ /** The stop ended the run without saving its terminal state, which a reconcile frame reports. */+ persistenceFailed?: boolean;+ /**+ * The server confirmed it stopped the stream, whose abort frame carries the saved response. A+ * request that ends without that frame leaves the host to reload what the server kept.+ */+ stopFramed?: boolean;+ /** The conversation a stop's answer named, authoritative while the chat still holds `new`. */+ stoppedConversationId?: string;+ /** Resolves once a stop sent for this generation was answered, either way. */+ stopAnswered?: Promise<void>;+ /** The stop in flight or confirmed, which a second stop joins instead of sending again. */+ stopping?: Promise<ChatAbortResult>;/** A turn that ended before its preparation installed a response, so it has none to report. */responseless?: boolean;};@@ -182,15 +228,32 @@ type ActiveRequest = {stream?: ChatStream;/** The generation this request runs or attaches to. */generation: Generation;- /** Set while attaching to a generation the server answered the start with, before it attaches. */- attaching?: boolean;+ /**+ * Set while attaching to the generation the server answered the start with, before it attaches,+ * naming the stream a stop addresses meanwhile.+ */+ reattach?: { streamId?: string };/*** The stream came from attaching to a running generation, whose HTTP failure ends only the* attachment unless the server says the generation is gone.*/attached?: boolean;+ /** The generation the start was answered with; a stream of another one starts a new record. */+ inheritedGeneration?: number;+ /** The error the request settled with when its connection dropped. */+ disconnected?: Error;/** Set once the start was handed to the transport, so the server may be running it. */sent?: boolean;+ /**+ * The conversation the start was sent under. One sent under `new` created a conversation of its+ * own, so no answer about another start or conversation resolves it if it is lost.+ */+ sentUnder?: string;+ /**+ * Set once the server answered for the start after it was cancelled, which can happen before the+ * request settles, so the stop that cancelled it owes nothing for it.+ */+ resolved?: boolean;/** Resolves once the request settled and released the chat. */finished: Promise<void>;finish: () => void;@@ -204,7 +267,7 @@ const createActiveRequest = (generation: Generation = {}): ActiveRequest => {return { controller: new AbortController(), generation, finished, finish };};-/** Settles with `value`, or rejects once `signal` aborts, so a disposal never waits on it. */+/** Settles with `value`, or rejects once `signal` aborts, so a stop never waits on it. */const untilAborted = <T>(value: T | Promise<T>, signal: AbortSignal): Promise<T> =>new Promise<T>((resolve, reject) => {const onAbort = () => reject(signal.reason);@@ -291,6 +354,74 @@ const getApplyFailure = (event: ChatEvent, failure: unknown, attached: boolean):: { kind: 'error', error, disconnect: true };};+/** A run that ended on its own before a stop reached it, whose final frame never arrived. */+const getSettledOutcome = (+ status: ChatStreamAbortResult['terminalStatus'],+ settled: Settled = {},+): Outcome => {+ if (status === 'error') {+ return { kind: 'error', error: new Error('The response failed'), disconnect: false, settled };+ }+ return status === 'aborted' ? { kind: 'abort', settled } : { kind: 'complete', settled };+};++/** What a confirmed stop ends a request with when no terminal frame said otherwise. */+const getStopOutcome = (stop: {+ settledAs?: ChatStreamAbortResult['terminalStatus'];+ persistenceFailed?: boolean;+ stopFramed?: boolean;+ /** The conversation the stop's answer named, which the host reloads. */+ stoppedConversationId?: string;+}): Outcome => {+ const settled: Settled =+ stop.stoppedConversationId != null ? { conversationId: stop.stoppedConversationId } : {};+ if (stop.persistenceFailed) {+ return { kind: 'abort', settled: { ...settled, reason: 'abort_persistence_failed' } };+ }+ if (stop.settledAs) {+ return getSettledOutcome(stop.settledAs, settled);+ }+ /** Read only where no abort frame ended the request, so the saved response was never received. */+ return stop.stopFramed ? { kind: 'abort', settled } : { kind: 'abort' };+};++/** The answer for a stop the server says found no generation, as an already-settled run. */+const goneStop: ChatStreamAbortResult = { success: false, settled: true, code: 'NO_ACTIVE_RUN' };++const isStreamAbort = (result: ChatAbortResult): result is ChatStreamAbortResult =>+ result != null && 'success' in result;++/**+ * How a stop's answer says the run had already ended on its own: a settled stream, or an+ * Assistants answer of `null`, which finds no run left and leaves the host to reload what it kept.+ */+const getSettledAs = (result: ChatAbortResult): ChatStreamAbortResult['terminalStatus'] => {+ if (result === null) {+ return 'complete';+ }+ return isStreamAbort(result) && result.settled+ ? (result.terminalStatus ?? 'complete')+ : undefined;+};++/**+ * What a stop hands back to the host. Steers come back only from a stop that ended the run: one+ * that settled first leaves them to its own terminal frame, and an unsaved one has none to trust.+ */+const getStopResult = (result: ChatAbortResult, conversationId?: string): ChatStopResult => {+ if (!isStreamAbort(result)) {+ /** An Assistants run's answer carries the conversation, which a first turn's server created. */+ const created = result?.conversation?.conversationId ?? undefined;+ return { status: 'stopped', ...(created != null && { conversationId: created }) };+ }+ const ended = !result.settled && !result.persistenceFailed;+ return {+ status: 'stopped',+ ...(conversationId != null && { conversationId }),+ ...(ended && result.pendingSteers && { pendingSteers: result.pendingSteers }),+ };+};+/** The ids a frame names for the conversation and the response its generation produces. */type FrameIdentity = { conversationId?: string | null; responseMessageId?: string };@@ -529,16 +660,6 @@ const undoOptimisticWrite = (record: OptimisticWrite, current: TMessage[]): TMesreturn next;};-/**- * Closes the stream of a start that answered after the chat let it go. Only a disposal lets a- * start go, and a disposed chat leaves the server's generation running, as it does an attached one.- */-const closeLateStart = (sent: ChatSendResult): void => {- if (sent.status === 'stream') {- sent.stream.close();- }-};-/*** One conversation's turn lifecycle, framework free. AI SDK: `AbstractChat`.*@@ -558,9 +679,18 @@ export class Chat {/** Set while the chat writes the state, whose own report of that write the chat announces itself. */private writing = false;private revision = 0;+ /** Aborted on dispose, which ends every wait on the server so no caller outlives the chat. */+ private readonly lifetime = new AbortController();+ /** The newest start handed to the transport, whose conversation a late answer must not replace. */+ private latestStart?: ActiveRequest;+ /**+ * A start that reached the transport and lost its response, with nothing to address it by. It+ * stays the caller's to stop until an answer resolves that start, or one its conversation covers.+ */+ private lostStart?: ActiveRequest;/*** The conversation this chat runs under: its id, until the server names the one it created for- * a chat started under `new`. Every later turn addresses that one.+ * a chat started under `new`. Every later start and stop addresses that one.*/private conversation: string;@@ -630,6 +760,317 @@ export class Chat {return this.request({ trigger: 'continue-message', messageId }, requestOptions);}+ /**+ * Stops the turn in flight. A request still starting is cancelled; an attached stream is+ * stopped on the server, and this resolves once the stream reported its end. Rejects when the+ * server refused the stop, leaving the stream attached. Resolves with the steers the run never+ * injected, for the host to restore, or `unaddressable` without contacting the server when the+ * chat holds no frame-backed identity for the generation.+ */+ async stop(): Promise<ChatStopResult> {+ if (this.disposed) {+ /** A disposed chat leaves the server's generation running, as dispose does. */+ return { status: 'idle' };+ }+ const active = this.active;+ if (!active) {+ /** The lost start is still the caller's. */+ return this.lostStart ? unaddressable : { status: 'idle' };+ }+ if (!active.stream && !active.reattach) {+ active.controller.abort();+ await active.finished;+ /**+ * A start already handed to the transport may be running on the server with no frame naming+ * it; a late stream is stopped by `dropLateStart`, but one that never arrives is the caller's.+ */+ const own: ChatStopResult =+ active.sent && !active.resolved ? unaddressable : { status: 'stopped' };+ return this.orUnaddressed(own);+ }+ const { generation } = active;+ if (!generation.endpoint) {+ throw new Error('The generation cannot be stopped without its endpoint');+ }+ const streamId = active.stream?.streamId ?? active.reattach?.streamId;+ const target = {+ endpoint: generation.endpoint,+ streamId,+ generationCreatedAt: active.stream?.generationCreatedAt ?? active.inheritedGeneration,+ abortKey: streamId == null ? this.abortKey(generation) : undefined,+ };+ if (!this.isAddressable(target)) {+ return unaddressable;+ }+ const result = await this.stopGeneration(generation, target);+ return this.orUnaddressed(await this.endStopped(active, generation, result));+ }++ /**+ * A stop's answer, unless a start this chat lost may still run on the server with nothing to+ * address it by; then the caller still owes its separate abort.+ */+ private orUnaddressed(result: ChatStopResult): ChatStopResult {+ /** Only an answer about the lost start clears it, not a turn a callback started meanwhile. */+ return this.lostStart ? unaddressable : result;+ }++ /** Sends a stop and records its answer on the generation, where every attachment reads it. */+ private stopGeneration(+ generation: Generation,+ target: Omit<ChatAbortRequest, 'chatId'>,+ ): Promise<ChatAbortResult> {+ if (generation.stopping) {+ return generation.stopping;+ }+ /** A start sent while the stop waited may run in a conversation of its own, which wins. */+ const since = this.latestStart;+ const answer = this.abortOnServer(target).then((result) => {+ generation.stopped = true;+ this.adoptStopAnswer(generation, result, since);+ generation.settledAs = getSettledAs(result);+ if (!generation.settledAs && isStreamAbort(result) && result.persistenceFailed) {+ generation.persistenceFailed = true;+ }+ generation.stopFramed =+ isStreamAbort(result) && !generation.settledAs && !generation.persistenceFailed;+ return result;+ });+ generation.stopping = answer;+ generation.stopAnswered = answer.then(+ () => undefined,+ () => {+ /** A refused stop leaves the generation running, so the next stop is sent anew. */+ generation.stopping = undefined;+ },+ );+ return answer;+ }++ /** Ends the request attached to a generation the server confirmed stopped. */+ private async endStopped(+ active: ActiveRequest,+ generation: Generation,+ result: ChatAbortResult,+ ): Promise<ChatStopResult> {+ const owns = () => active.generation === generation;+ if (!owns()) {+ /** The request moved on to another generation while the stop was in flight; that one runs on. */+ return getStopResult(result, generation.stoppedConversationId);+ }+ if (result && 'runMessages' in result) {+ await this.mergeRunMessages(result.runMessages, () => this.active === active && owns());+ if (!owns()) {+ /** The request opened another generation while the merge waited its turn. */+ return getStopResult(result, generation.stoppedConversationId);+ }+ active.controller.abort();+ active.stream?.close();+ } else if (result === null || result === goneStop || generation.settledAs) {+ /**+ * No run was left to stop, or it had already ended on its own: the answer is the end, so the+ * attachment closes rather than waiting on a terminal frame that may never arrive.+ */+ active.controller.abort();+ active.stream?.close();+ } else if (!active.stream && !generation.persistenceFailed) {+ /**+ * Still attaching: nothing will report the end, so the stop ends the request here. An+ * unsaved stop stays attached for the reconcile frame that reports it.+ */+ active.controller.abort();+ }+ await active.finished;+ if (this.disposed) {+ /** A chat disposed while the stop ended its request writes no state. */+ return getStopResult(result, generation.stoppedConversationId);+ }+ this.notify();+ return getStopResult(result, generation.stoppedConversationId);+ }++ /**+ * Drops a start that reached the server after it was cancelled. A stop also ends its generation+ * there; a disposal leaves it running, as it does an attached one.+ */+ private dropLateStart(active: ActiveRequest, sent: ChatSendResult): void {+ if (sent.status === 'stream') {+ sent.stream.close();+ }+ const answered = sent.status === 'settled' || sent.status === 'replaced';+ if (answered && sent.generationProtocolVersion === 2) {+ /**+ * The server finished the start on its own, or answered it with a newer generation this+ * request does not own and leaves alone; either way its stop has nothing left to reach, and+ * the answer names the conversation a chat started under `new` adopts.+ */+ if (!this.startsAfter(active)) {+ this.learnConversation(sent.conversationId);+ }+ this.resolveLostStart(active);+ return;+ }+ const { endpoint } = active.generation;+ if (this.disposed || !endpoint || sent.status !== 'stream') {+ return;+ }+ const { streamId, generationCreatedAt } = sent.stream;+ const target = {+ endpoint,+ streamId,+ generationCreatedAt,+ abortKey: streamId == null ? this.abortKey(active.generation) : undefined,+ };+ if (!this.isAddressable(target)) {+ /** Nothing names it; the stop already reported it unaddressable to the caller. */+ return;+ }+ void this.abortOnServer(target).then(+ (result) => {+ /** The answer names the conversation the start created, unless a newer start owns the chat. */+ this.adoptStopAnswer(active.generation, result, active);+ this.resolveLostStart(active);+ },+ (error: unknown) =>+ this.disposed+ ? undefined+ : this.callHost(+ this.init.onError,+ error instanceof Error ? error : new Error(String(error)),+ ),+ );+ }++ /**+ * Records the conversation a stop's answer names for `generation`, which a chat started under+ * `new` adopts unless a start sent after `since` may run in a conversation of its own.+ */+ private adoptStopAnswer(+ generation: Generation,+ result: ChatAbortResult,+ since: ActiveRequest | undefined,+ ): void {+ if (isStreamAbort(result)) {+ generation.stoppedConversationId = this.stoppedConversationId(generation, result);+ }+ if (this.startsAfter(since)) {+ return;+ }+ this.learnConversation(+ isStreamAbort(result)+ ? generation.stoppedConversationId+ : result?.conversation?.conversationId,+ );+ }++ /**+ * A start the chat reported lost is now answered for: its marker clears, and the failure it+ * reported resolves unless a newer turn owns the chat.+ */+ private resolveLostStart(active: ActiveRequest): void {+ active.resolved = true;+ if (this.lostStart !== active) {+ return;+ }+ this.lostStart = undefined;+ const failed = active.disconnected;+ if (this.disposed || this.active || !failed || this.error !== failed) {+ return;+ }+ this.init.state.error = undefined;+ this.init.state.status = 'ready';+ this.notify();+ }++ /**+ * Whether a start sent after `since` is still running or lost, so it may own a conversation of its own+ * that a late answer about an older generation must not replace.+ */+ private startsAfter(since: ActiveRequest | undefined): boolean {+ const latest = this.latestStart;+ return (+ latest != null && latest !== since && (latest === this.active || latest === this.lostStart)+ );+ }++ /**+ * An Assistants run's stream ends without a final frame; the stop's answer carries it as the+ * conversation's stored messages, so they replace the list and rows the run deleted go with it.+ * `owns` is checked when the write runs, so a turn that took over while it queued keeps its list.+ */+ private mergeRunMessages(runMessages: TMessage[], owns: () => boolean): Promise<void> {+ return this.executor.run(() => {+ if (!owns() || runMessages.length === 0) {+ return;+ }+ const local = new Map(this.messages.map((message) => [message.messageId, message]));+ this.write(runMessages.map((message) => ({ ...local.get(message.messageId), ...message })));+ });+ }++ /**+ * The conversation a stop that named its stream ended. The answer names only the stream, so the+ * generation's known conversation wins; a first turn no frame named yet falls back to that+ * stream id, which a resumable server keys by the conversation it created. A run that settled+ * before the stop reached it names that stream as `streamId` instead of `aborted`.+ */+ private stoppedConversationId(+ generation: Generation,+ result: ChatStreamAbortResult,+ ): string | undefined {+ const stream = result.aborted ?? result.streamId;+ if (stream == null) {+ return undefined;+ }+ const known = generation.conversationId ?? this.conversationId;+ return known !== Constants.NEW_CONVO ? known : stream;+ }++ /** `conversationId:responseMessageId` of a run with no resumable stream (Assistants). */+ private abortKey(generation: Generation): string | undefined {+ const conversationId = generation.conversationId ?? this.conversationId;+ if (conversationId === Constants.NEW_CONVO) {+ /** Before its sync frame, a turn under `new` has no id the server knows it by. */+ return undefined;+ }+ return generation.responseId ? `${conversationId}:${generation.responseId}` : undefined;+ }++ /** Whether a stop can name the generation: by its stream, its run key, or a created chat. */+ private isAddressable(target: Omit<ChatAbortRequest, 'chatId'>): boolean {+ return (+ target.streamId != null ||+ target.abortKey != null ||+ this.conversationId !== Constants.NEW_CONVO+ );+ }++ /**+ * Stops a generation on the server. A run that already reached its own end counts as stopped;+ * a refusal rejects.+ */+ private async abortOnServer(target: Omit<ChatAbortRequest, 'chatId'>): Promise<ChatAbortResult> {+ if (this.lifetime.signal.aborted) {+ throw this.lifetime.signal.reason;+ }+ const result = await untilAborted(+ this.init.transport+ .abort({ chatId: this.conversationId, ...target })+ .catch((error: unknown) => {+ if (isGone(error as ChatTransportError)) {+ /** Nothing is left to stop, so the run ended on its own and the host reloads it. */+ return goneStop;+ }+ throw error;+ }),+ this.lifetime.signal,+ );+ if (result && 'success' in result && !result.success && !result.settled) {+ throw new Error(result.error ?? 'The server refused the stop');+ }+ return result;+ }+/** Returns a failed chat to `ready`. AI SDK: `clearError`. */clearError(): void {if (this.status !== 'error') {@@ -664,6 +1105,7 @@ export class Chat {return;}this.disposed = true;+ this.lifetime.abort(new Error('The chat was disposed'));const active = this.active;this.active = undefined;active?.controller.abort();@@ -686,7 +1128,7 @@ export class Chat {state.connection = 'idle';this.notify();}- /** Whoever waits on the request, such as its send, is released with the chat. */+ /** Whoever waits on the request, such as its send or a stop, is released with the chat. */active?.finish();this.listeners.clear();this.releaseState?.();@@ -745,9 +1187,12 @@ export class Chat {}/** Only now is the turn's response in the list, so a failure before this reports none. */active.generation.responseless = undefined;+ active.generation.endpoint = prepared.payload.endpoint ?? undefined;active.generation.conversationId = prepared.payload.conversationId ?? undefined;const { signal } = active.controller;active.sent = true;+ active.sentUnder = this.conversation;+ this.latestStart = active;const result = await openUntilAborted(this.init.transport.sendMessages({...options,@@ -758,10 +1203,10 @@ export class Chat {abortSignal: signal,}),signal,- closeLateStart,+ (sent) => this.dropLateStart(active, sent),);if (signal.aborted) {- closeLateStart(result);+ this.dropLateStart(active, result);throw signal.reason;}if (result.status === 'replaced' && result.generationProtocolVersion !== 2) {@@ -775,12 +1220,30 @@ export class Chat {if (result.status !== 'stream') {this.learnConversation(result.conversationId);}+ if (this.lostStart?.sentUnder !== Constants.NEW_CONVO) {+ /**+ * The server took a start in the lost start's conversation, where one generation runs, so it+ * owns or superseded it. One sent under `new` created a conversation no other start covers.+ */+ this.lostStart = undefined;+ }let stream: ChatStream | null = null;if (result.status === 'stream') {stream = result.stream;/** A start the server attached to a generation already running is an attachment too. */active.attached = result.stream.resumed === true;} else if (result.status === 'replaced') {+ /**+ * The replacement it names, so a stream of yet another generation gets its own record.+ * Recorded before the rollback notifies, so a stop made then addresses the replacement.+ */+ active.inheritedGeneration = result.generationCreatedAt ?? undefined;+ active.reattach = { streamId: result.streamId };+ active.attached = true;+ /** The replacement's response is not this turn's placeholder; its first frame names it. */+ active.generation.responseId = undefined;+ active.generation.responseUnknown = true;+ active.generation.conversationId = result.conversationId;const rollback = active.optimistic;if (rollback) {/** The server ran a newer generation instead, so this turn's optimistic write is undone. */@@ -788,12 +1251,6 @@ export class Chat {this.write(undoOptimisticWrite(rollback, this.messages));});}- /** The replacement's response is not this turn's placeholder; its first frame names it. */- active.generation.responseId = undefined;- active.generation.responseUnknown = true;- active.generation.conversationId = result.conversationId;- active.attaching = true;- active.attached = true;if (signal.aborted) {throw signal.reason;}@@ -814,6 +1271,14 @@ export class Chat {(opened) => opened?.close(),);}+ if (!stream && active.generation.stopAnswered) {+ /** A stop still in flight decides how an empty reconnect ended. */+ await active.generation.stopAnswered;+ }+ if (!stream && active.generation.stopped) {+ this.settle(getStopOutcome(active.generation), active);+ return;+ }if (!stream) {/** The server finished the turn, or the generation replacing it, before it attached. */const conversationId = result.status === 'stream' ? undefined : result.conversationId;@@ -833,11 +1298,22 @@ export class Chat {if (signal.aborted) {/** The request was cancelled while the stream was still being opened. */stream.close();- this.settle({ kind: 'abort' }, active);+ this.settle(getStopOutcome(active.generation), active);return;}active.stream = stream;- active.attaching = undefined;+ if (+ active.inheritedGeneration != null &&+ stream.generationCreatedAt != null &&+ stream.generationCreatedAt !== active.inheritedGeneration+ ) {+ /**+ * The attachment found another generation, whose response no frame has named yet. It gets+ * its own record, so a stop of the one it was answered with does not end it.+ */+ const { endpoint, conversationId } = active.generation;+ active.generation = { endpoint, conversationId, responseUnknown: true };+ }let outcome: Outcome | undefined;/** The event this chat is applying, whose failure is the chat's, not the generation's. */let handling: ChatEvent | undefined;@@ -850,6 +1326,7 @@ export class Chat {await this.executor.run(() => {if (!signal.aborted) {handling = event;+ /** Recorded first, so a host that stops from the event's own callbacks names the run. */this.adopt(active.generation, getFrameIdentity(event));outcome = this.apply(event, active);handling = undefined;@@ -872,6 +1349,15 @@ export class Chat {} finally {stream.close();}+ const unresolved = !outcome || (outcome.kind === 'error' && outcome.disconnect);+ if (unresolved && active.generation.stopAnswered) {+ /** A stream that ended during a stop is settled by the server's answer to it. */+ await active.generation.stopAnswered;+ }+ if (active.generation.stopped && unresolved) {+ /** Including one the stop itself closed, whose answer may say the run had already ended. */+ outcome = getStopOutcome(active.generation);+ }if (!outcome && signal.aborted) {outcome = { kind: 'abort' };}@@ -934,17 +1420,31 @@ export class Chat {}private toOutcome(error: unknown, active: ActiveRequest): Outcome {+ if (+ active.controller.signal.aborted &&+ active.sent &&+ !active.resolved &&+ !active.stream &&+ !active.reattach+ ) {+ /** A start cancelled before its answer may still run on the server, so its end is unknown. */+ return {+ kind: 'error',+ error: new Error('The stop could not reach the generation, which may still be running'),+ disconnect: true,+ };+ }if (active.controller.signal.aborted) {- return { kind: 'abort' };+ return getStopOutcome(active.generation);}const failure = error instanceof Error ? error : new Error(String(error));/*** A request that never got a response may still be running on the server, and so may a* generation a failed attachment never reached, unless the server answered that it is gone.*/+ const attaching = active.reattach != null && !active.stream;const disconnect =- isRetryableNetworkError(failure) ||- (active.attaching === true && !isGone(failure as ChatTransportError));+ isRetryableNetworkError(failure) || (attaching && !isGone(failure as ChatTransportError));return { kind: 'error', error: failure, disconnect };}@@ -952,6 +1452,13 @@ export class Chat {if (this.active !== active) {return;}+ if (outcome.kind === 'error' && outcome.disconnect) {+ active.disconnected = outcome.error;+ if (active.sent && !active.stream && !active.reattach && !active.resolved) {+ /** The start may have reached the server, which answered nothing this chat can address. */+ this.lostStart = active;+ }+ }/*** Released and published as one change before anyone is told, so a subscriber or callback* that starts the next turn is not overwritten by this one's terminal state.@@ -959,7 +1466,15 @@ export class Chat {this.active = undefined;const { responseId, responseUnknown, responseless, conversationId } = active.generation;const named = conversationId !== Constants.NEW_CONVO ? conversationId : undefined;- this.publish({ ...outcome, conversationId: named }, responseId, responseUnknown, responseless);+ /** A lost start still owed its own abort keeps the failure it reported. */+ const owed = this.lostStart !== active ? this.lostStart?.disconnected : undefined;+ this.publish(+ { ...outcome, conversationId: named },+ responseId,+ responseUnknown,+ responseless,+ owed,+ );}/**@@ -995,9 +1510,11 @@ export class Chat {responseId: string | undefined,responseUnknown = false,responseless = false,+ /** A failure another start reported, which this terminal state does not resolve. */+ owed?: Error,): void {const { state } = this.init;- const status: ChatStatus = outcome.kind === 'error' ? 'error' : 'ready';+ const status: ChatStatus = outcome.kind === 'error' || owed ? 'error' : 'ready';/*** One terminal state, with the chat's listeners told once it is all set. A store subscriber* told of a field may start the next turn, which then owns the fields this one has not set.@@ -1011,7 +1528,7 @@ export class Chat {state.status = status;}if (!this.active) {- state.error = outcome.kind === 'error' ? outcome.error : undefined;+ state.error = outcome.kind === 'error' ? outcome.error : owed;}} finally {this.writing = false;