From 08a6e7fb28af96412f96978529caba14c68b49fd Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Thu, 29 Oct 2026 15:22:14 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=9B=91=20feat:=20Stop=20the=20Turn=20in?= =?UTF-8?q?=20Flight=20From=20the=20Chat=20Core=20(#17577)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: Stop the Turn in Flight From the Chat Core * fix: Adopt the Conversation a Late Stream's Stop Names and Record a Replacement Before Its Rollback Notifies --- packages/chat/src/core/__tests__/chat.spec.ts | 1145 ++++++++++++- .../src/core/__tests__/generations.spec.ts | 1488 +++++++++++++++++ packages/chat/src/core/chat.ts | 585 ++++++- 3 files changed, 3182 insertions(+), 36 deletions(-) create mode 100644 packages/chat/src/core/__tests__/generations.spec.ts diff --git a/packages/chat/src/core/__tests__/chat.spec.ts b/packages/chat/src/core/__tests__/chat.spec.ts index 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(() => 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>>((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(() => 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((resolve) => { + open = resolve; + }), + ), + abort: jest.fn( + () => + new Promise((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 | undefined; const { chat, stream, transport } = setup({ @@ -703,6 +1199,229 @@ describe('Chat', () => { }, ); + 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(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(() => 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[] = []; + 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(() => 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(() => 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; + 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.ts new file mode 100644 index 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((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['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((resolve) => setTimeout(resolve, 0)); + } +}; + +type Harness = { + chat: Chat; + prepare: jest.Mock, [ChatPrepareRequest]>; + transport: jest.Mocked>; + 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 & { 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>; + 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 Promise> = { + /** 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) => + 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 Promise> = { + 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 + >; + /** 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 Promise> = { + 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) => { + 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 + > | null; + /** The stop's own result: `ok`, `unaddressable`, or a rejection message fragment. */ + outcome: string; +}; + +const stopExits: Array<[string, (h: Harness) => Promise, 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; 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]> = [ + [ + '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((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 | 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.ts index 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; /** @@ -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; + /** The stop in flight or confirmed, which a second stop joins instead of sending again. */ + stopping?: Promise; /** 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; 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 = (value: T | Promise, signal: AbortSignal): Promise => new Promise((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[]): TMes return 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 { + 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, + ): Promise { + 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 { + 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 { + 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): 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): Promise { + 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;