From d4374f02deef1ac70f61b6538208e0ef4ffeadb5 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Thu, 29 Oct 2026 20:49:41 +0100 Subject: [PATCH] =?UTF-8?q?=E2=8F=B8=EF=B8=8F=20feat:=20Answer,=20Restore?= =?UTF-8?q?=20and=20Stop=20a=20Paused=20Generation=20From=20the=20Chat=20C?= =?UTF-8?q?ore=20(#17587)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: Answer, Restore and Stop a Paused Generation From the Chat Core * fix: Retire a Pause the Server Refused Once Its Probe Owns the Chat * fix: Keep a Pause the Server Refused Over for Later Reads and Replays --- e2e/specs/mock/scenarios/chat-package.spec.ts | 77 + packages/chat/src/core/__tests__/chat.spec.ts | 1562 ++++++++++++++++- .../src/core/__tests__/generations.spec.ts | 1041 ++++++++++- packages/chat/src/core/chat.ts | 697 +++++++- packages/chat/src/core/types.ts | 4 +- 5 files changed, 3344 insertions(+), 37 deletions(-) diff --git a/e2e/specs/mock/scenarios/chat-package.spec.ts b/e2e/specs/mock/scenarios/chat-package.spec.ts index 8172c1954d..6587a532ec 100644 --- a/e2e/specs/mock/scenarios/chat-package.spec.ts +++ b/e2e/specs/mock/scenarios/chat-package.spec.ts @@ -337,4 +337,81 @@ test.describe('the built @librechat/chat package', () => { cached: 1, }); }); + + test('a host answers a pause on a stream that names no generation @scenario:a-host-answers-a-pause-on-a-stream-without-a-generation', () => { + test.setTimeout(120_000); + const dist = resolve(repoRoot, 'packages/chat/dist'); + expect(existsSync(dist), 'packages/chat/dist is missing: run npm run build').toBe(true); + + /** An older server streams the pause without dating its generation; the action id fences the answer. */ + const probe = ` + const { Chat } = require('@librechat/chat'); + let messages = []; + const events = []; + let push; + const stream = { + streamId: 'convo-1', + close() {}, + async *[Symbol.asyncIterator]() { + while (true) { + const event = events.shift() ?? (await new Promise((resolve) => { push = resolve; })); + yield event; + if (event.type === 'final') return; + } + }, + }; + const emit = (event) => { if (push) { const p = push; push = undefined; p(event); } else events.push(event); }; + const answers = []; + const chat = new Chat({ + id: 'convo-1', + state: { error: undefined, connection: 'idle', status: 'ready', + get messages() { return messages; }, + replaceMessages(next) { messages = next; } }, + transport: { + sendMessages: async () => ({ status: 'stream', stream }), + reconnectToStream: async () => null, + abort: async () => ({ success: true }), + resume: async (request) => { + answers.push(request); + return { status: 'resuming', streamId: 'convo-1', conversationId: 'convo-1' }; + }, + }, + prepareRequest: () => ({ payload: { endpoint: 'agents' } }), + resumeSelection: () => ({ endpoint: 'agents' }), + }); + const tick = () => new Promise((resolve) => setTimeout(resolve, 0)); + (async () => { + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await tick(); + emit({ type: 'pending_action', data: { + actionId: 'action-1', streamId: 'convo-1', conversationId: 'convo-1', createdAt: 1, + payload: { type: 'ask_user_question', question: { question: 'Which?' }, tool_call_id: 'ask-1' }, + } }); + await tick(); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'yes' }); + const cleared = chat.pendingAction === undefined; + emit({ type: 'final', data: { final: true, responseMessage: { messageId: 'r1', text: 'Done' } } }); + await sent; + const [answer] = answers; + process.stdout.write(JSON.stringify({ + answered: answers.length, + actionId: answer.actionId, + answer: answer.answer, + dated: 'generationCreatedAt' in answer, + cleared, + status: chat.status, + })); + })(); + `; + const loaded = run(process.execPath, ['-e', probe], { cwd: resolve(repoRoot, 'client') }); + expect(loaded.status, loaded.output).toBe(0); + expect(JSON.parse(loaded.stdout)).toEqual({ + answered: 1, + actionId: 'action-1', + answer: 'yes', + dated: false, + cleared: true, + status: 'ready', + }); + }); }); diff --git a/packages/chat/src/core/__tests__/chat.spec.ts b/packages/chat/src/core/__tests__/chat.spec.ts index a26431dd15..d8ef4bc57a 100644 --- a/packages/chat/src/core/__tests__/chat.spec.ts +++ b/packages/chat/src/core/__tests__/chat.spec.ts @@ -1,4 +1,4 @@ -import { StepEvents, buildTree } from 'librechat-data-provider'; +import { ContentTypes, StepEvents, buildTree } from 'librechat-data-provider'; import type { Agents, TMessage, TPayload, ChatEvent } from 'librechat-data-provider'; import type { ChatStream, @@ -352,6 +352,68 @@ describe('Chat', () => { }); }); + it('releases an answer still waiting on its resume when the chat is disposed', async () => { + const { chat, stream, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + transport.resume.mockImplementationOnce(() => new Promise(() => undefined)); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ + type: 'pending_action', + data: { + actionId: 'action-1', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + expiresAt: Date.now() + 60_000, + payload: { type: 'ask_user_question', question: { question: 'Which?' }, tool_call_id: 'a' }, + } as Agents.PendingAction, + }); + await flush(); + const answered = chat.addToolOutput({ toolCallId: 'a', output: 'Yes' }); + await flush(); + + chat.dispose(); + + await expect(answered).rejects.toThrow('The chat was disposed'); + await sent; + }); + + describe('a replayed stale pause', () => { + const pause = { + actionId: 'action-1', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + expiresAt: Date.now() + 60_000, + payload: { type: 'ask_user_question', question: { question: 'Which?' }, tool_call_id: 'a' }, + } as Agents.PendingAction; + + it('stays out of the host reducer when this chat already resumed it', async () => { + const applyEvent = jest.fn(); + const { chat, transport } = setup({ + applyEvent, + resumeSelection: () => ({ endpoint: 'agents' }), + }); + const continuation = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + transport.reconnectToStream.mockResolvedValueOnce(continuation); + chat.restorePendingAction(pause, 100); + await chat.addToolOutput({ toolCallId: 'a', output: 'Yes' }); + await flush(); + + continuation.push({ type: 'pending_action', data: pause }); + await flush(); + + expect(applyEvent).not.toHaveBeenCalledWith( + expect.objectContaining({ type: 'pending_action' }), + expect.anything(), + ); + continuation.push(finalEvent()); + await flush(); + }); + }); + it('streams a turn whose first frame is a pause', async () => { const { chat, stream } = setup(); const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); @@ -1028,6 +1090,43 @@ describe('Chat', () => { expect(replaced.chat.status).toBe('ready'); }); + it('resumes a pause of a replacing generation with the timestamp the start reported', async () => { + const stream = createStream({ streamId: 'stream-2' }); + const { chat, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { + sendMessages: jest.fn(async () => ({ + status: 'replaced' as const, + generationProtocolVersion: 2, + conversationId: 'convo-1', + streamId: 'stream-2', + generationCreatedAt: 200, + })), + reconnectToStream: jest.fn(async () => stream), + }, + ); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ + type: 'pending_action', + data: { + actionId: 'action-3', + streamId: 'stream-2', + conversationId: 'convo-1', + createdAt: 1, + payload: { type: 'ask_user_question', question: { question: 'Which?' } }, + } as Agents.PendingAction, + }); + await flush(); + + await chat.addToolOutput({ toolCallId: 'action-3', output: 'Blue' }); + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 200, actionId: 'action-3' }), + ); + stream.push(finalEvent()); + await sent; + }); + it('stops a replacing generation on the server while it is still attaching', async () => { const { chat, transport } = setup( {}, @@ -1467,6 +1566,49 @@ describe('Chat', () => { expect(chat.status).toBe('ready'); }); + it('keeps a newer pause restored while a dropped Assistants run merged its stop', async () => { + 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(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(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + const newer = { + actionId: 'action-newer', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 2, + payload: { type: 'ask_user_question', question: { question: 'Which?' }, tool_call_id: 'q' }, + } as Agents.PendingAction; + let restored = false; + const unsubscribe = chat.subscribe(() => { + if (!restored && chat.messages[1]?.text === 'Partial') { + restored = true; + chat.restorePendingAction(newer, 900); + } + }); + + await chat.stop(); + unsubscribe(); + + expect(chat.messages[1].text).toBe('Partial'); + expect(chat.pendingAction?.actionId).toBe('action-newer'); + }); + it('keeps the reattachment target of a reconnect that failed on the network', async () => { const failure = Object.assign(new Error('Network Error'), { code: 'ERR_NETWORK' }); const { chat, transport } = setup( @@ -1979,8 +2121,798 @@ describe('Chat', () => { expect(onError).not.toHaveBeenCalled(); }); + describe('paused generations', () => { + const toolCall = (id: string) => ({ + type: ContentTypes.TOOL_CALL, + tool_call: { + id, + name: 'search', + args: '{}', + type: 'tool_call', + approval: { actionId: 'action-1', allowed_decisions: ['approve', 'reject'] }, + }, + }); + + const approvalAction = { + actionId: 'action-1', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + payload: { + type: 'tool_approval', + action_requests: [ + { name: 'search', arguments: '{}', tool_call_id: 'call-1' }, + { name: 'search', arguments: '{}', tool_call_id: 'call-2' }, + ], + review_configs: [], + }, + } as Agents.PendingAction; + + const askAction = { + actionId: 'action-2', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + payload: { + type: 'ask_user_question', + question: { question: 'Which?' }, + tool_call_id: 'ask-1', + }, + } as Agents.PendingAction; + + const pause = async (action: Agents.PendingAction, overrides: Partial = {}) => { + const paused = setup({ + resumeSelection: () => ({ endpoint: 'agents', agent_id: 'agent-1' }), + prepareRequest: () => ({ + payload, + messages: [ + userMessage, + { ...placeholder, content: [toolCall('call-1'), toolCall('call-2')] } as TMessage, + ], + }), + ...overrides, + }); + const sent = paused.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + paused.stream.push({ type: 'pending_action', data: action }); + await flush(); + return { ...paused, sent }; + }; + + it('shows a decision on a paused call nested inside a subagent', async () => { + const subagent = { + type: ContentTypes.TOOL_CALL, + tool_call: { + id: 'subagent-1', + name: 'subagent', + args: '{}', + type: 'tool_call', + subagent_content: [toolCall('call-1')], + }, + }; + const { chat, stream, sent } = await pause(approvalAction, { + prepareRequest: () => ({ + payload, + messages: [ + userMessage, + { ...placeholder, content: [subagent, toolCall('call-2')] } as TMessage, + ], + }), + }); + + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + + const [outer] = chat.messages[1].content as unknown as Array<{ + tool_call: { subagent_content: Array<{ tool_call: Agents.ToolCall }> }; + }>; + expect(outer.tool_call.subagent_content[0].tool_call).toMatchObject({ + approval: { decision: 'approve' }, + }); + stream.push(finalEvent()); + await sent; + }); + + it('shows each decision and resumes once the whole batch is decided', async () => { + const { chat, transport, stream, sent } = await pause(approvalAction); + expect(chat.pendingAction).toBe(approvalAction); + + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + expect(transport.resume).not.toHaveBeenCalled(); + const [first] = chat.messages[1].content as Array<{ tool_call: Agents.ToolCall }>; + expect(first.tool_call).toMatchObject({ approval: { decision: 'approve' } }); + + await chat.addToolApprovalResponse({ id: 'call-2', approved: false, reason: 'No' }); + expect(transport.resume).toHaveBeenCalledWith({ + endpoint: 'agents', + agent_id: 'agent-1', + conversationId: 'convo-1', + generationCreatedAt: 100, + actionId: 'action-1', + decisions: [ + { tool_call_id: 'call-1', decision: 'approve' }, + { tool_call_id: 'call-2', decision: 'reject', reason: 'No' }, + ], + }); + expect(chat.pendingAction).toBeUndefined(); + + stream.push(finalEvent()); + await sent; + }); + + it('keeps the decisions of a pause the stream replays after a reconnect', async () => { + const { chat, transport, stream, sent } = await pause(approvalAction); + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + stream.push({ type: 'pending_action', data: { ...approvalAction } }); + await flush(); + + await chat.addToolApprovalResponse({ id: 'call-2', approved: false }); + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ + decisions: [ + { tool_call_id: 'call-1', decision: 'approve' }, + { tool_call_id: 'call-2', decision: 'reject' }, + ], + }), + ); + stream.push(finalEvent()); + await sent; + }); + + it('does not resume a batch whose pause was replaced while its last decision was shown', async () => { + const { chat, transport, state } = setup(); + state.replaceMessages([ + userMessage, + { ...placeholder, content: [toolCall('call-1'), toolCall('call-2')] } as TMessage, + ]); + chat.restorePendingAction(approvalAction, 500); + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + const unsubscribe = chat.subscribe(() => { + if (chat.pendingAction === approvalAction) { + chat.restorePendingAction(askAction, 500); + } + }); + + await chat.addToolApprovalResponse({ id: 'call-2', approved: true }); + unsubscribe(); + + expect(transport.resume).not.toHaveBeenCalled(); + expect(chat.pendingAction).toBe(askAction); + }); + + it('lets a subscriber start a turn once a reconnect drops a pause that ended elsewhere', async () => { + const { chat, transport, stream } = setup(); + chat.restorePendingAction(askAction, 500); + let next: Promise | undefined; + const unsubscribe = chat.subscribe(() => { + if (!chat.pendingAction && !next) { + next = Promise.resolve(); + next = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + } + }); + + await chat.resumeStream({ streamId: 'convo-1' }); + unsubscribe(); + + expect(chat.status).toBe('submitted'); + await flush(); + expect(transport.sendMessages).toHaveBeenCalled(); + stream.push(finalEvent()); + await next; + }); + + it('resumes a replayed pause once, with the decisions made before the replay', async () => { + const { chat, transport, stream, sent } = await pause(approvalAction); + let accept: (() => void) | undefined; + transport.resume.mockImplementationOnce( + () => + new Promise((resolve) => { + accept = () => + resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' }); + }), + ); + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + const resumed = chat.addToolApprovalResponse({ id: 'call-2', approved: true }); + await flush(); + stream.push({ type: 'pending_action', data: { ...approvalAction } }); + await flush(); + + await expect(chat.addToolApprovalResponse({ id: 'call-2', approved: false })).rejects.toThrow( + 'already being resumed', + ); + accept?.(); + await resumed; + expect(transport.resume).toHaveBeenCalledTimes(1); + expect(chat.pendingAction).toBeUndefined(); + stream.push(finalEvent()); + await sent; + }); + + it('keeps the decisions of a pause a status check restores again', async () => { + const { chat, transport } = setup(); + chat.restorePendingAction(approvalAction, 500); + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + chat.restorePendingAction({ ...approvalAction }, 500); + + await chat.addToolApprovalResponse({ id: 'call-2', approved: true }); + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ + decisions: [ + { tool_call_id: 'call-1', decision: 'approve' }, + { tool_call_id: 'call-2', decision: 'approve' }, + ], + }), + ); + }); + + it('does not reattach for a pause replaced while its resume was in flight', async () => { + let accept: (() => void) | undefined; + const { chat, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { + resume: jest.fn( + () => + new Promise((resolve) => { + accept = () => + resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' }); + }), + ), + }, + ); + chat.restorePendingAction(askAction, 500); + const answered = chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + await flush(); + const next = { ...approvalAction, actionId: 'action-9' } as Agents.PendingAction; + chat.restorePendingAction(next, 900); + + accept?.(); + await answered; + await flush(); + + expect(transport.reconnectToStream).not.toHaveBeenCalled(); + expect(chat.pendingAction).toBe(next); + }); + + it('shows only the reason of the latest decision for a call', async () => { + const { chat, stream, sent } = await pause(approvalAction); + await chat.addToolApprovalResponse({ id: 'call-1', approved: false, reason: 'No' }); + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + + const call = chat.messages[1].content?.[0] as { tool_call: Agents.ToolCall }; + expect(call.tool_call).toMatchObject({ approval: { decision: 'approve' } }); + expect((call.tool_call as { approval?: { reason?: string } }).approval).not.toHaveProperty( + 'reason', + ); + stream.push(finalEvent()); + await sent; + }); + + it('resumes a batch once when its last decisions arrive together', async () => { + const { chat, transport, stream, sent } = await pause(approvalAction); + transport.resume.mockImplementationOnce( + () => + new Promise((resolve) => + setTimeout( + () => resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' }), + 10, + ), + ), + ); + + await Promise.all([ + chat.addToolApprovalResponse({ id: 'call-1', approved: true }), + chat.addToolApprovalResponse({ id: 'call-2', approved: true }), + ]); + + expect(transport.resume).toHaveBeenCalledTimes(1); + stream.push(finalEvent()); + await sent; + }); + + it('attaches to the continuation of a pause restored without a stream', async () => { + const continuation = createStream(); + const { chat, transport } = setup( + {}, + { reconnectToStream: jest.fn(async () => continuation) }, + ); + + chat.restorePendingAction(askAction, 500); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + await flush(); + + expect(transport.reconnectToStream).toHaveBeenCalledWith( + expect.objectContaining({ streamId: 'convo-1', generationCreatedAt: 500, resume: true }), + ); + continuation.push(stepEvent); + continuation.push(finalEvent()); + await flush(); + expect(chat.status).toBe('ready'); + expect(chat.messages[1].text).toBe('Hello'); + }); + + it('does not reattach once disposed while a resume is in flight', async () => { + let accept: (() => void) | undefined; + const { chat, transport } = setup( + {}, + { + resume: jest.fn( + () => + new Promise((resolve) => { + accept = () => + resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' }); + }), + ), + }, + ); + + chat.restorePendingAction(askAction, 500); + const answered = chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + await flush(); + chat.dispose(); + await expect(answered).rejects.toThrow('The chat was disposed'); + accept?.(); + await flush(); + + expect(transport.reconnectToStream).not.toHaveBeenCalled(); + await expect(chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] })).rejects.toThrow( + 'disposed', + ); + }); + + it('stops the continuation of a restored pause with the generation it resumed', async () => { + const continuation = createStream({ streamId: 'convo-1' }); + const { chat, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { reconnectToStream: jest.fn(async () => continuation) }, + ); + transport.abort.mockImplementation(async () => { + continuation.push(finalEvent({ terminalStatus: 'aborted' })); + return { success: true }; + }); + + chat.restorePendingAction(askAction, 500); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + await flush(); + continuation.push(stepEvent); + await flush(); + await chat.stop(); + + expect(transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ endpoint: 'agents', generationCreatedAt: 500 }), + ); + expect(chat.status).toBe('ready'); + }); + + it('stops a restored pause on the server while its continuation is still attaching', async () => { + const { chat, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { reconnectToStream: jest.fn(() => new Promise(() => undefined)) }, + ); + chat.restorePendingAction(askAction, 500); + + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + await flush(); + await chat.stop(); + await resumed; + + expect(transport.abort).toHaveBeenCalledWith({ + chatId: 'convo-1', + endpoint: 'agents', + streamId: 'convo-1', + generationCreatedAt: 500, + }); + expect(chat.pendingAction).toBeUndefined(); + expect(chat.status).toBe('ready'); + }); + + it('refuses decisions and answers once disposed', async () => { + const { chat, transport } = setup(); + chat.restorePendingAction(askAction, 500); + chat.dispose(); + + await expect(chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' })).rejects.toThrow( + 'disposed', + ); + expect(transport.resume).not.toHaveBeenCalled(); + }); + + it('drops a restored pause once a reconnect finds nothing running', async () => { + const { chat, transport } = setup(); + chat.restorePendingAction(askAction, 500); + + await chat.resumeStream({ streamId: 'convo-1' }); + + expect(transport.reconnectToStream).toHaveBeenCalled(); + expect(chat.pendingAction).toBeUndefined(); + }); + + it('drops a restored pause when the reattached stream is another generation', async () => { + const other = createStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + const { chat } = setup({}, { reconnectToStream: jest.fn(async () => other) }); + chat.restorePendingAction(askAction, 100); + + const resumed = chat.resumeStream({ streamId: 'convo-1' }); + await flush(); + + expect(chat.pendingAction).toBeUndefined(); + other.push(finalEvent()); + await resumed; + }); + + it('refuses to restore a pause while a stream is attached', async () => { + const { chat, stream, sent } = await pause(askAction); + const newer = { ...askAction, actionId: 'action-7' } as Agents.PendingAction; + + expect(() => chat.restorePendingAction(newer, 900)).toThrow('in flight'); + expect(chat.pendingAction).toBe(askAction); + stream.push(finalEvent()); + await sent; + }); + + it('drops a restored pause when an explicit reconnect names another generation', async () => { + const other = createStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + const { chat } = setup({}, { reconnectToStream: jest.fn(async () => other) }); + chat.restorePendingAction(askAction, 100); + + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + await flush(); + + expect(chat.pendingAction).toBeUndefined(); + other.push(finalEvent()); + await resumed; + }); + + it('ignores the replay of a pause it already resumed', async () => { + let attach: (() => void) | undefined; + const continuation = createStream({ streamId: 'convo-1' }); + const { chat } = setup( + {}, + { + reconnectToStream: jest.fn( + () => + new Promise((resolve) => { + attach = () => resolve(continuation); + }), + ), + }, + ); + chat.restorePendingAction(askAction, 500); + const resumed = chat.resumeStream({ streamId: 'convo-1' }); + await flush(); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + attach?.(); + await flush(); + continuation.push({ type: 'pending_action', data: askAction }); + await flush(); + + expect(chat.pendingAction).toBeUndefined(); + continuation.push(finalEvent()); + await resumed; + }); + + it('reports a continuation that finished before it attached as settled', async () => { + const { chat, state, onFinish } = setup(); + state.error = new Error('dropped'); + state.status = 'error'; + chat.restorePendingAction(askAction, 500); + + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + await flush(); + + expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isSettled: true })); + expect(chat.status).toBe('ready'); + expect(chat.error).toBeUndefined(); + }); + + it('submits edit, respond and session-scoped decisions as given', async () => { + const { chat, transport, stream, sent } = await pause(approvalAction); + await chat.addToolApprovalResponse({ + id: 'call-1', + approved: true, + decision: 'edit', + editedArguments: { q: 'cats' }, + }); + await chat.addToolApprovalResponse({ id: 'call-2', approved: true, scope: 'session' }); + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ + decisions: [ + { tool_call_id: 'call-1', decision: 'edit', editedArguments: { q: 'cats' } }, + { tool_call_id: 'call-2', decision: 'approve', scope: 'session' }, + ], + }), + ); + stream.push(finalEvent()); + await sent; + }); + + it('stops a restored pause of a newer generation, not an older dropped one', async () => { + const { chat, stream, sent, transport } = await pause(askAction, { + resumeSelection: () => ({ endpoint: 'agents' }), + }); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + const newer = { + ...askAction, + actionId: 'action-8', + streamId: 'convo-1', + } as Agents.PendingAction; + chat.restorePendingAction(newer, 900); + + await chat.stop(); + + expect(transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 900 }), + ); + expect(chat.pendingAction).toBeUndefined(); + }); + + it('holds new turns behind a restored pause until it is stopped on the server', async () => { + const { chat, transport } = setup({ resumeSelection: () => ({ endpoint: 'agents' }) }); + chat.restorePendingAction(askAction, 500); + + await expect(chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] })).rejects.toThrow( + 'paused generation', + ); + expect(transport.sendMessages).not.toHaveBeenCalled(); + + await chat.stop(); + expect(transport.abort).toHaveBeenCalledWith({ + chatId: 'convo-1', + endpoint: 'agents', + streamId: 'convo-1', + generationCreatedAt: 500, + }); + expect(chat.pendingAction).toBeUndefined(); + }); + + it('keeps the pause when only the connection drops', async () => { + const { chat, stream, sent } = await pause(askAction); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + + expect(chat.status).toBe('error'); + expect(chat.pendingAction).toBe(askAction); + }); + + it('refuses a decision once the batch is being resumed', async () => { + const single = { + ...approvalAction, + payload: { + ...approvalAction.payload, + action_requests: [{ name: 'search', arguments: '{}', tool_call_id: 'call-1' }], + }, + } as Agents.PendingAction; + const { chat, transport, stream, sent } = await pause(single); + let accept: (() => void) | undefined; + transport.resume.mockImplementationOnce( + () => + new Promise((resolve) => { + accept = () => + resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' }); + }), + ); + + const approved = chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + await flush(); + await expect(chat.addToolApprovalResponse({ id: 'call-1', approved: false })).rejects.toThrow( + 'already being resumed', + ); + accept?.(); + await approved; + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ + decisions: [{ tool_call_id: 'call-1', decision: 'approve' }], + }), + ); + stream.push(finalEvent()); + await sent; + }); + + it('drops the pause of a stopped generation whose stream disconnects instead of aborting', async () => { + const { chat, transport, stream, sent } = await pause(askAction); + transport.abort.mockImplementation(async () => { + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + return { success: true }; + }); + + await chat.stop(); + await sent; + + expect(chat.pendingAction).toBeUndefined(); + }); + + it('drops a pause that arrives while a confirmed stop is in flight', async () => { + const { chat, transport, stream } = setup(); + let confirm: (() => void) | undefined; + transport.abort.mockImplementation( + () => + new Promise((resolve) => { + confirm = () => resolve({ success: true }); + }), + ); + const turn = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push(stepEvent); + await flush(); + + const stopped = chat.stop(); + stream.push({ type: 'pending_action', data: askAction }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await flush(); + confirm?.(); + await stopped; + await turn; + + expect(chat.pendingAction).toBeUndefined(); + }); + + it('keeps the pause of a turn started while a slow stop was in flight', async () => { + const first = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + const second = createStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + let confirm: (() => void) | undefined; + const { chat, transport } = setup( + {}, + { + sendMessages: jest + .fn() + .mockResolvedValueOnce({ status: 'stream', stream: first }) + .mockResolvedValueOnce({ status: 'stream', stream: second }), + abort: jest.fn( + () => + new Promise((resolve) => { + confirm = () => resolve({ success: true }); + }), + ), + }, + ); + const firstTurn = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + const stopped = chat.stop(); + first.push(finalEvent()); + await firstTurn; + + const secondTurn = chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] }); + await flush(); + second.push({ type: 'pending_action', data: askAction }); + await flush(); + confirm?.(); + await stopped; + + expect(transport.abort).toHaveBeenCalledTimes(1); + expect(chat.pendingAction).toBe(askAction); + second.push(finalEvent()); + await secondTurn; + }); + + it('reports ready once a stop ends a pause its dropped connection left in error', async () => { + const { chat, stream, sent } = await pause(askAction); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + expect(chat.status).toBe('error'); + + await chat.stop(); + + expect(chat.pendingAction).toBeUndefined(); + expect(chat.status).toBe('ready'); + expect(chat.error).toBeUndefined(); + }); + + it('drops the pause when the generation aborts or fails', async () => { + const aborted = await pause(askAction); + aborted.stream.push({ type: 'abort', data: {} } as ChatEvent); + await aborted.sent; + expect(aborted.chat.pendingAction).toBeUndefined(); + await expect( + aborted.chat.addToolOutput({ toolCallId: 'ask-1', output: 'x' }), + ).rejects.toThrow('No question is pending'); + + const failed = await pause(askAction); + failed.stream.push({ type: 'error', data: 'boom' } as ChatEvent); + await failed.sent; + expect(failed.chat.pendingAction).toBeUndefined(); + }); + + it('resumes a later pause with its own generation, not the previous one', async () => { + const first = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + const second = createStream({ streamId: 'convo-1' }); + const { chat, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { + sendMessages: jest + .fn() + .mockResolvedValueOnce({ status: 'stream', stream: first }) + .mockResolvedValueOnce({ status: 'stream', stream: second }), + }, + ); + + const firstTurn = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + first.push(finalEvent()); + await firstTurn; + + const secondTurn = chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] }); + await flush(); + second.push({ type: 'pending_action', data: askAction }); + await flush(); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'x' }); + /** The second stream names no generation, so the answer is fenced by its action alone. */ + expect(transport.resume).toHaveBeenCalledTimes(1); + const [request] = (transport.resume as jest.Mock).mock.calls[0]; + expect(request).toMatchObject({ actionId: askAction.actionId, answer: 'x' }); + expect(request).not.toHaveProperty('generationCreatedAt'); + expect(chat.pendingAction).toBeUndefined(); + second.push(finalEvent()); + await secondTurn; + }); + + it('refuses a decision for a call the pause does not hold', async () => { + const { chat, stream, sent } = await pause(approvalAction); + + await expect(chat.addToolApprovalResponse({ id: 'other', approved: true })).rejects.toThrow( + 'not awaiting approval', + ); + await expect(chat.addToolOutput({ toolCallId: 'call-1', output: 'x' })).rejects.toThrow( + 'No question is pending', + ); + + stream.push(finalEvent()); + await sent; + await expect(chat.addToolApprovalResponse({ id: 'call-1', approved: true })).rejects.toThrow( + 'No tool approval is pending', + ); + }); + + it('answers a question with free text or keyed answers', async () => { + const { chat, transport, stream, sent } = await pause(askAction); + + await expect(chat.addToolOutput({ toolCallId: 'other', output: 'x' })).rejects.toThrow( + 'not awaiting an answer', + ); + await chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' }); + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ actionId: 'action-2', answer: 'Blue' }), + ); + + stream.push(finalEvent()); + await sent; + + chat.restorePendingAction(askAction, 400); + await chat.addToolOutput({ toolCallId: 'ask-1', output: { q1: 'Blue' } }); + expect(transport.resume).toHaveBeenLastCalledWith( + expect.objectContaining({ generationCreatedAt: 400, answers: { q1: 'Blue' } }), + ); + }); + + it('refuses to answer over a transport that cannot resume', async () => { + const { chat, transport, stream, sent } = await pause(askAction); + (transport as Partial).resume = undefined; + + await expect(chat.addToolOutput({ toolCallId: 'ask-1', output: 'Blue' })).rejects.toThrow( + 'cannot resume', + ); + expect(chat.pendingAction).toBe(askAction); + + stream.push(finalEvent()); + await sent; + }); + }); + describe('stop answers and reattachment targets', () => { const steer = { steerId: 'steer-1', text: 'Shorter' }; + const pausedAction = { + actionId: 'action-5', + streamId: 'new', + createdAt: 1, + payload: { + type: 'ask_user_question', + question: { question: 'Which?' }, + tool_call_id: 'ask-5', + }, + } as Agents.PendingAction; it('hands back the steers a stop found uninjected, under the conversation it stopped', async () => { const { chat, stream, transport } = setup(); @@ -2136,6 +3068,18 @@ describe('Chat', () => { ); }); + it('reports a restored pause a reconnect finds finished elsewhere as settled', async () => { + const { chat, transport, onFinish } = setup(); + chat.restorePendingAction({ ...pausedAction, streamId: 'convo-1' }, 500); + transport.reconnectToStream.mockResolvedValueOnce(null); + + await chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + + expect(chat.pendingAction).toBeUndefined(); + expect(onFinish).toHaveBeenCalledTimes(1); + expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isSettled: true })); + }); + it('reattaches a dropped first turn under the conversation its sync frame assigned', async () => { const { chat, stream, transport, onFinish } = setup({ id: 'new' }); const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); @@ -2530,6 +3474,145 @@ describe('Chat', () => { ); }); + it('keeps the pause of a generation whose stream failed while read, and a stop ends it', async () => { + const failing: ChatStream = { + streamId: 'convo-1', + close: () => undefined, + async *[Symbol.asyncIterator]() { + yield { type: 'pending_action', data: pausedAction } as ChatEvent; + throw new Error('Malformed frame'); + }, + }; + const { chat, transport } = setup(); + transport.sendMessages.mockResolvedValueOnce({ status: 'stream', stream: failing }); + + await chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + + /** The stream failed, not the generation, which still waits on its pause. */ + expect(chat.status).toBe('error'); + expect(chat.pendingAction?.actionId).toBe('action-5'); + transport.abort.mockResolvedValueOnce({ success: true }); + await chat.stop(); + expect(transport.abort).toHaveBeenCalledTimes(1); + expect(chat.pendingAction).toBeUndefined(); + transport.sendMessages.mockResolvedValueOnce({ + status: 'settled', + conversationId: 'convo-1', + generationProtocolVersion: 2, + }); + await expect( + chat.sendMessage({ parts: [{ type: 'text', text: 'Again' }] }), + ).resolves.toBeUndefined(); + }); + + it('reports a continuation that ended while an earlier reconnect was still opening', async () => { + let open: ((stream: ChatStream | null) => void) | undefined; + const { chat, onFinish } = setup( + {}, + { + reconnectToStream: jest.fn( + () => + new Promise((resolve) => { + open = resolve; + }), + ), + }, + ); + chat.restorePendingAction({ ...pausedAction, streamId: 'convo-1' }, 500); + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + await flush(); + + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + open?.(null); + await resumed; + + expect(chat.status).toBe('ready'); + expect(onFinish).toHaveBeenCalledTimes(1); + expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isSettled: true })); + }); + + it('ignores a status read that restores a pause this chat already resumed', async () => { + const { chat } = setup(); + const action = { ...pausedAction, streamId: 'convo-1' }; + chat.restorePendingAction(action, 500); + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + await flush(); + + chat.restorePendingAction(action, 500); + + expect(chat.pendingAction).toBeUndefined(); + }); + + it('lets a completion callback start a turn once a stopped pause ended', async () => { + const next: Promise[] = []; + const { chat, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + onFinish: () => { + if (next.length > 0) { + return; + } + transport.sendMessages.mockResolvedValueOnce({ + status: 'settled', + conversationId: 'convo-1', + generationProtocolVersion: 2, + }); + next.push(chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] })); + }, + }); + transport.reconnectToStream.mockImplementation( + (request) => + new Promise((_resolve, reject) => { + request.abortSignal?.addEventListener('abort', () => reject(new Error('aborted'))); + }), + ); + chat.restorePendingAction({ ...pausedAction, streamId: 'convo-1' }, 500); + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + await flush(); + + await chat.stop(); + await resumed; + + expect(next).toHaveLength(1); + await expect(next[0]).resolves.toBeUndefined(); + expect(chat.pendingAction).toBeUndefined(); + }); + + it('reports nothing for a stop answered after the chat was disposed', async () => { + for (const restore of [false, true]) { + let answer: ((result: ChatAbortResult) => void) | undefined; + const { chat, stream, transport, onFinish } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { + abort: jest.fn( + () => + new Promise((resolve) => { + answer = resolve; + }), + ), + }, + ); + if (restore) { + chat.restorePendingAction({ ...pausedAction, streamId: 'convo-1' }, 500); + } else { + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + } + const finishes = onFinish.mock.calls.length; + + const stopped = chat.stop(); + await flush(); + chat.dispose(); + await expect(stopped).rejects.toThrow('The chat was disposed'); + answer?.({ success: true, persistenceFailed: true }); + await flush(); + + expect(transport.abort).toHaveBeenCalledTimes(1); + expect(onFinish).toHaveBeenCalledTimes(finishes); + } + }); + it('sends the request options of a turn to the generation that replaced it', async () => { const stream = createStream(); const { chat, transport } = setup( @@ -2556,6 +3639,183 @@ describe('Chat', () => { ); }); + it('reattaches an answered first-turn pause under the conversation the server assigned', async () => { + const { chat, transport, onFinish } = setup( + { id: 'new' }, + { + resume: jest.fn(async () => ({ + streamId: 'convo-9', + conversationId: 'convo-9', + status: 'resuming' as const, + })), + }, + ); + + chat.restorePendingAction(pausedAction, 500); + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + await flush(); + + expect(transport.reconnectToStream).toHaveBeenCalledWith( + expect.objectContaining({ chatId: 'convo-9', streamId: 'convo-9' }), + ); + expect(onFinish).toHaveBeenCalledWith( + expect.objectContaining({ isSettled: true, conversationId: 'convo-9' }), + ); + }); + + it('keeps the assigned conversation of a continuation that dropped before its sync frame', async () => { + const continuation = createStream({ streamId: 'convo-9', generationCreatedAt: 500 }); + const { chat, transport, onFinish } = setup( + { id: 'new', resumeSelection: () => ({ endpoint: 'agents' }) }, + { + resume: jest.fn(async () => ({ + streamId: 'convo-9', + conversationId: 'convo-9', + status: 'resuming' as const, + })), + reconnectToStream: jest.fn(async () => continuation), + }, + ); + chat.restorePendingAction(pausedAction, 500); + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + await flush(); + continuation.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await flush(); + expect(onFinish).toHaveBeenLastCalledWith(expect.objectContaining({ isDisconnect: true })); + transport.reconnectToStream.mockResolvedValueOnce(null); + + await chat.resumeStream(); + + expect(transport.reconnectToStream).toHaveBeenLastCalledWith( + expect.objectContaining({ chatId: 'convo-9' }), + ); + expect(onFinish).toHaveBeenLastCalledWith( + expect.objectContaining({ isSettled: true, conversationId: 'convo-9' }), + ); + }); + + it('ends a reattachment of the same generation by a detached stop answered after it', async () => { + const { chat, stream, transport, onFinish } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'pending_action', data: pausedAction }); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + expect(chat.pendingAction?.actionId).toBe('action-5'); + + let answer: (result: ChatAbortResult) => void = () => undefined; + transport.abort.mockImplementationOnce( + () => + new Promise((resolve) => { + answer = resolve; + }), + ); + const stopped = chat.stop(); + await flush(); + const reattached = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + transport.reconnectToStream.mockResolvedValueOnce(reattached); + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + await flush(); + expect(chat.connection).toBe('live'); + + answer({ success: true }); + await flush(); + reattached.close(); + await resumed; + + await expect(stopped).resolves.toEqual({ status: 'stopped' }); + expect(transport.abort).toHaveBeenCalledTimes(1); + expect(chat.status).toBe('ready'); + expect(chat.pendingAction).toBeUndefined(); + expect(onFinish).toHaveBeenLastCalledWith( + expect.objectContaining({ isAbort: true, isDisconnect: false }), + ); + }); + + it('ends a reattachment of a restored pause by the stop answered after it', async () => { + const { chat, transport, onFinish } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + chat.restorePendingAction(pausedAction, 500); + let answer: (result: ChatAbortResult) => void = () => undefined; + transport.abort.mockImplementationOnce( + () => + new Promise((resolve) => { + answer = resolve; + }), + ); + const stopped = chat.stop(); + await flush(); + const reattached = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + transport.reconnectToStream.mockResolvedValueOnce(reattached); + const resumed = chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + await flush(); + expect(chat.connection).toBe('live'); + + answer({ success: true }); + await flush(); + reattached.close(); + await resumed; + + await expect(stopped).resolves.toEqual({ status: 'stopped' }); + expect(transport.abort).toHaveBeenCalledTimes(1); + expect(chat.status).toBe('ready'); + expect(chat.pendingAction).toBeUndefined(); + expect(onFinish).toHaveBeenLastCalledWith( + expect.objectContaining({ isAbort: true, isDisconnect: false }), + ); + }); + + it('does not end another generation a restored pause reattachment found by its stop', async () => { + const { chat, transport, onFinish } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + chat.restorePendingAction(pausedAction, 500); + let answer: (result: ChatAbortResult) => void = () => undefined; + transport.abort.mockImplementationOnce( + () => + new Promise((resolve) => { + answer = resolve; + }), + ); + const stopped = chat.stop(); + await flush(); + const newer = createStream({ streamId: 'convo-1', generationCreatedAt: 700 }); + transport.reconnectToStream.mockResolvedValueOnce(newer); + const resumed = chat.resumeStream({ streamId: 'convo-1' }); + await flush(); + + answer({ success: true }); + await stopped; + newer.close(); + await resumed; + + expect(onFinish).toHaveBeenLastCalledWith(expect.objectContaining({ isDisconnect: true })); + }); + + it('addresses a stop made as a newer reattachment clears a restored pause to that one', async () => { + const { chat, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + transport.reconnectToStream.mockImplementationOnce(() => new Promise(() => undefined)); + chat.restorePendingAction(pausedAction, 100); + const stops: Promise[] = []; + chat.subscribe(() => { + if (!chat.pendingAction && stops.length === 0) { + stops.push(chat.stop().catch(() => undefined)); + } + }); + + void chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + await Promise.all(stops); + + expect(transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 200 }), + ); + }); + it.each([ ['its preparation fails', 'prepare'], ['the server refuses its start', 'start'], @@ -2630,6 +3890,60 @@ describe('Chat', () => { }, ); + it('ignores a late status read restoring a pause whose generation was stopped', async () => { + const { chat, stream } = setup({ resumeSelection: () => ({ endpoint: 'agents' }) }); + chat.restorePendingAction(pausedAction, 500); + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + + chat.restorePendingAction(pausedAction, 500); + + expect(chat.pendingAction).toBeUndefined(); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] }); + await flush(); + stream.push(finalEvent()); + await expect(sent).resolves.toBeUndefined(); + }); + + it('ignores a late status read restoring a streamed pause of a stopped dropped generation', async () => { + const { chat, stream, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'pending_action', data: pausedAction }); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + + chat.restorePendingAction(pausedAction, 100); + + expect(chat.pendingAction).toBeUndefined(); + const next = createStream({ streamId: 'convo-1', generationCreatedAt: 200 }); + transport.sendMessages.mockResolvedValueOnce({ status: 'stream', stream: next }); + const again = chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] }); + await flush(); + next.push(finalEvent()); + await expect(again).resolves.toBeUndefined(); + }); + + it('answers a first-turn pause under the conversation its sync frame assigned', async () => { + const { chat, stream, transport } = setup({ id: 'new' }); + void chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ + type: 'sync', + data: { conversationId: 'convo-9', responseMessage: placeholder }, + } as ChatEvent); + stream.push({ type: 'pending_action', data: pausedAction }); + await flush(); + + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ conversationId: 'convo-9', actionId: 'action-5' }), + ); + }); + it('still stops a dropped generation after a retry rejected as an unnegotiated replacement', async () => { const { chat, stream, transport } = setup({ resumeSelection: () => ({ endpoint: 'agents' }), @@ -2729,6 +4043,25 @@ describe('Chat', () => { ); }); + it('keeps the stop target of a dropped generation when a stale pause of a stopped one is read', async () => { + const { chat, stream, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + chat.restorePendingAction(pausedAction, 500); + await chat.stop(); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + + chat.restorePendingAction(pausedAction, 500); + + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + expect(transport.abort).toHaveBeenLastCalledWith( + expect.objectContaining({ streamId: 'convo-1', generationCreatedAt: 100 }), + ); + }); + it('reports the response of a resumed generation no frame named as unknown', async () => { const resumed = createStream({ streamId: 'convo-1', generationCreatedAt: 300 }); const { chat, state, transport, onFinish } = setup({ @@ -2832,6 +4165,21 @@ describe('Chat', () => { ); }); + it('ignores a late status read for any generation a stop ended, not only the latest', async () => { + const { chat, transport } = setup({ resumeSelection: () => ({ endpoint: 'agents' }) }); + const older = { ...pausedAction, streamId: 'convo-1' }; + const newer = { ...older, actionId: 'action-6' }; + + chat.restorePendingAction(older, 500); + await chat.stop(); + chat.restorePendingAction(newer, 600); + await chat.stop(); + chat.restorePendingAction(older, 500); + + expect(transport.abort).toHaveBeenCalledTimes(2); + expect(chat.pendingAction).toBeUndefined(); + }); + it('reports a cancelled start the server may still run as a disconnect, not an abort', async () => { const { chat, onFinish } = setup( {}, @@ -2851,6 +4199,30 @@ describe('Chat', () => { await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' }); }); + it('answers a pause on a reattached stream by the dropped generation it continued', async () => { + const reattached = createStream({ streamId: 'convo-1' }); + const { chat, stream, transport } = setup( + { resumeSelection: () => ({ endpoint: 'agents' }) }, + { reconnectToStream: jest.fn(async () => reattached) }, + ); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + + const resumed = chat.resumeStream(); + await flush(); + reattached.push({ type: 'pending_action', data: { ...pausedAction, streamId: 'convo-1' } }); + await flush(); + await chat.addToolOutput({ toolCallId: 'ask-5', output: 'Blue' }); + reattached.push(finalEvent()); + await resumed; + + expect(transport.resume).toHaveBeenCalledWith( + expect.objectContaining({ actionId: 'action-5', generationCreatedAt: 100 }), + ); + }); + it('reports the stored tail when a local turn without a named response reattaches', async () => { const reattached = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); const { chat, stream, onFinish } = setup( @@ -3035,6 +4407,34 @@ describe('Chat', () => { expect(chat.messages.map((message) => message.messageId)).toEqual(['user-1', 'response-1']); }); + it('ignores a late status read for a generation whose own stream ended it', async () => { + const { chat, stream } = setup(); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push(finalEvent()); + await sent; + + chat.restorePendingAction({ ...pausedAction, expiresAt: Date.now() + 60_000 }, 100); + + expect(chat.pendingAction).toBeUndefined(); + }); + + it('ignores a late status read for a generation a reattachment found finished', async () => { + const { chat, stream, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + transport.reconnectToStream.mockResolvedValueOnce(null); + await chat.resumeStream(); + + chat.restorePendingAction({ ...pausedAction, expiresAt: Date.now() + 60_000 }, 100); + + expect(chat.pendingAction).toBeUndefined(); + }); + 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 }); @@ -3059,6 +4459,42 @@ describe('Chat', () => { await expect(chat.stop()).resolves.toEqual({ status: 'idle' }); }); + it('keeps a dropped generation stoppable through a late status read of a stopped one', async () => { + const { chat, stream, transport } = setup({ + resumeSelection: () => ({ endpoint: 'agents' }), + }); + chat.restorePendingAction(pausedAction, 50); + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent); + await sent; + transport.abort.mockClear(); + + chat.restorePendingAction({ ...pausedAction, expiresAt: Date.now() + 60_000 }, 50); + + expect(chat.pendingAction).toBeUndefined(); + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + expect(transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ streamId: 'convo-1', generationCreatedAt: 100 }), + ); + }); + + it('reports the response of a restored pause a stop found already gone as unknown', async () => { + const { chat, state, transport, onFinish } = setup({ + resumeSelection: () => ({ endpoint: 'assistants' }), + }); + state.replaceMessages([userMessage, { ...placeholder, messageId: 'other-branch' }]); + transport.abort.mockResolvedValue(null); + chat.restorePendingAction({ ...pausedAction, expiresAt: Date.now() + 60_000 }, 500); + + await expect(chat.stop()).resolves.toEqual({ status: 'stopped' }); + + expect(onFinish).toHaveBeenLastCalledWith( + expect.objectContaining({ isSettled: true, isResponseUnknown: true, message: undefined }), + ); + }); + it('settles a named reattachment that finds its generation already finished', async () => { const { chat, transport, onFinish } = setup({ resumeSelection: () => ({ endpoint: 'agents' }), @@ -3072,6 +4508,31 @@ describe('Chat', () => { expect(onFinish).toHaveBeenCalledTimes(1); expect(onFinish).toHaveBeenCalledWith(expect.objectContaining({ isSettled: true })); }); + + it('ignores a late status read for a late start a stop already ended', 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 chat.stop(); + await sent; + deliver?.({ status: 'stream', stream: late }); + await flush(); + expect(transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 300 }), + ); + + chat.restorePendingAction({ ...pausedAction, expiresAt: Date.now() + 60_000 }, 300); + + expect(chat.pendingAction).toBeUndefined(); + }); }); describe('ids a turn reports', () => { @@ -3991,6 +5452,105 @@ describe('Chat attachments and reported conversations', () => { expect(rows(state.messages)).toEqual(atDispose?.rows); }, ); + + const toolCall = (id: string) => ({ + type: ContentTypes.TOOL_CALL, + tool_call: { + id, + name: 'search', + args: '{}', + type: 'tool_call', + approval: { actionId: 'action-1', allowed_decisions: ['approve', 'reject'] }, + }, + }); + const approval = { + actionId: 'action-1', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + payload: { + type: 'tool_approval', + action_requests: [{ name: 'search', arguments: '{}', tool_call_id: 'call-1' }], + review_configs: [], + }, + } as Agents.PendingAction; + + /** Starts a turn over `state` whose stream pauses for approval of `call-1`. */ + const pauseForApproval = async (state: ChatState) => { + const stream = createStream({ streamId: 'convo-1', generationCreatedAt: 100 }); + const paused = setup( + { + state, + resumeSelection: () => ({ endpoint: 'agents', agent_id: 'agent-1' }), + prepareRequest: jest.fn(() => ({ + payload, + messages: (current: TMessage[]) => [ + ...current, + userMessage, + { ...placeholder, content: [toolCall('call-1')] } as TMessage, + ], + })), + }, + { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) }, + ); + const sent = paused.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }); + await flush(); + stream.push({ type: 'pending_action', data: approval }); + await flush(); + return { ...paused, stream, sent }; + }; + + const isDecided = (messages: TMessage[]) => + messages.some((m) => JSON.stringify(m.content ?? []).includes('"decision":"approve"')); + + it.each([ + ['over a store that reports writes synchronously', false], + ['over a structurally shared store', true], + ])( + 'keeps a row a store subscriber appended inside an approval write and resumes once, %s', + async (_label, shared) => { + const state = createStore(shared); + const { chat, transport, stream, sent } = await pauseForApproval(state); + state.subscribe?.(() => { + const current = state.messages; + if (isDecided(current) && !current.some((m) => m.messageId === external.messageId)) { + state.replaceMessages([...current, external]); + } + }); + + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }); + + expect(transport.resume).toHaveBeenCalledTimes(1); + expect(state.messages.map((m) => m.messageId)).toContain(external.messageId); + stream.push(finalEvent({ requestMessage: null, responseMessage: null })); + await sent; + expect(state.messages.map((m) => m.messageId)).toContain(external.messageId); + }, + ); + + it.each([ + ['over a store that reports writes synchronously', false], + ['over a structurally shared store', true], + ])( + 'sends no resume once a store subscriber disposes the chat inside an approval write, %s', + async (_label, shared) => { + const state = createStore(shared); + const { chat, transport, sent } = await pauseForApproval(state); + let disposed = false; + state.subscribe?.(() => { + if (!disposed && isDecided(state.messages)) { + disposed = true; + chat.dispose(); + } + }); + + await chat.addToolApprovalResponse({ id: 'call-1', approved: true }).catch(() => undefined); + await sent; + + expect(disposed).toBe(true); + expect(transport.resume).not.toHaveBeenCalled(); + }, + ); }); 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 index b925be5d70..362b7c1873 100644 --- a/packages/chat/src/core/__tests__/generations.spec.ts +++ b/packages/chat/src/core/__tests__/generations.spec.ts @@ -1,5 +1,5 @@ import { StepEvents } from 'librechat-data-provider'; -import type { TMessage, TPayload, ChatEvent } from 'librechat-data-provider'; +import type { Agents, TMessage, TPayload, ChatEvent } from 'librechat-data-provider'; import type { ChatInit, ChatState, @@ -12,9 +12,9 @@ import type { ChatStream, ChatStatus, ChatTransport, + ChatSendResult, ChatConnection, ChatAbortResult, - ChatSendResult, } from '../types'; import { Chat } from '../chat'; @@ -89,6 +89,14 @@ const finalEvent = (data: Partial['data']> const dropEvent = { type: 'error', status: 0, data: 'offline' } as ChatEvent; +const askAction = { + actionId: 'action-1', + streamId: 'convo-1', + conversationId: 'convo-1', + createdAt: 1, + payload: { type: 'ask_user_question', question: { question: 'Which?' }, tool_call_id: 'ask-1' }, +} as Agents.PendingAction; + const networkError = () => Object.assign(new Error('Network Error'), { code: 'ERR_NETWORK' }); const flush = async () => { @@ -251,6 +259,17 @@ const states: Record Promise> = { ); await flush(); }, + /** Streaming a generation that paused for an answer. */ + paused: async (h) => { + await states.attached(h); + h.stream?.push({ type: 'pending_action', data: askAction }); + await flush(); + }, + /** A pause restored from a status check, with no stream attached. */ + restored: async (h) => { + h.chat.restorePendingAction(askAction, 500); + await flush(); + }, /** The server finished the turn before the chat attached. */ settled: async (h) => { h.transport.sendMessages.mockResolvedValue({ @@ -331,6 +350,10 @@ const events: Record Promise> = { h.stream = undefined; await events.stop(h); }, + restoreThenStop: async (h) => { + await events.restore(h); + await events.stop(h); + }, final: async (h) => { h.open?.(); await flush(); @@ -446,6 +469,15 @@ const events: Record Promise> = { await stopping; await flush(); }, + restore: async (h) => { + try { + h.chat.restorePendingAction({ ...askAction, actionId: 'action-9' }, 900); + h.outcome = 'ok'; + } catch (error) { + h.outcome = (error as Error).message; + } + await flush(); + }, }; type Expected = { @@ -459,6 +491,7 @@ type Expected = { >; /** What `transport.abort` was asked to stop, or `null` when it was not called. */ abort?: { streamId?: string; generationCreatedAt?: number } | null; + action?: string | null; /** The event's own result: `ok`, a rejection message fragment, or `sent:` for a new turn. */ outcome?: string; turn?: 'pending' | 'settled'; @@ -489,6 +522,7 @@ 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', 'restore', { status: 'submitted', finishes: 0, outcome: 'in flight' }], [ 'attached', @@ -513,6 +547,7 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ ['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' }], + ['attached', 'restore', { status: 'streaming', finishes: 0, outcome: 'in flight' }], [ 'detached', @@ -525,6 +560,7 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ }, ], ['detached', 'newTurn', { status: 'ready', finishes: 2, last: settled, outcome: 'sent:ok' }], + ['detached', 'restore', { status: 'error', finishes: 1, action: 'action-9', outcome: 'ok' }], [ 'reattaching', @@ -544,9 +580,48 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ 'newTurn', { status: 'ready', connection: 'reconnecting', finishes: 0, outcome: 'in flight' }, ], + ['reattaching', 'restore', { status: 'ready', finishes: 0, outcome: 'in flight' }], + + [ + 'paused', + 'stop', + { + status: 'ready', + finishes: 1, + last: aborted, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 100 }, + }, + ], + ['paused', 'networkDrop', { status: 'error', finishes: 1, last: dropped, action: 'action-1' }], + ['paused', 'final', { status: 'ready', finishes: 1, last: done, action: NONE }], + [ + 'paused', + 'newTurn', + { status: 'streaming', finishes: 0, action: 'action-1', outcome: 'in flight' }, + ], + + [ + 'restored', + 'stop', + { + status: 'ready', + finishes: 1, + last: stoppedUnframed, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 500 }, + }, + ], + [ + 'restored', + 'newTurn', + { status: 'ready', finishes: 0, action: 'action-1', outcome: 'paused generation' }, + ], + ['restored', 'restore', { status: 'ready', finishes: 0, action: 'action-9', outcome: 'ok' }], ['settled', 'stop', { status: 'ready', finishes: 1, last: settled, abort: NONE, outcome: 'ok' }], ['settled', 'newTurn', { status: 'ready', finishes: 2, outcome: 'sent:ok' }], + ['settled', 'restore', { status: 'ready', finishes: 1, action: 'action-9', outcome: 'ok' }], [ 'replaced', @@ -564,6 +639,7 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ ['aborted', 'stop', { status: 'ready', finishes: 1, last: aborted, abort: NONE, outcome: 'ok' }], ['aborted', 'newTurn', { status: 'ready', finishes: 2, outcome: 'sent:ok' }], + ['aborted', 'restore', { status: 'ready', finishes: 1, action: 'action-9', outcome: '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 }], @@ -584,6 +660,17 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ abort: { streamId: 'convo-1', generationCreatedAt: 100 }, }, ], + [ + 'detached', + 'restoreThenStop', + { + status: 'ready', + finishes: 2, + last: stoppedUnframed, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 900 }, + }, + ], [ 'reattaching', 'streamEnd', @@ -604,6 +691,28 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ abort: { streamId: 'convo-1', generationCreatedAt: 300 }, }, ], + [ + 'paused', + 'dropThenStop', + { + status: 'ready', + finishes: 2, + last: stoppedUnframed, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 100 }, + }, + ], + [ + 'restored', + 'restoreThenStop', + { + status: 'ready', + finishes: 1, + last: stoppedUnframed, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 900 }, + }, + ], ['replaced', 'streamEnd', { status: 'error', finishes: 1, last: dropped }], [ 'replaced', @@ -651,7 +760,33 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ outcome: 'ok', }, ], + [ + 'restored', + 'unsavedStop', + { + status: 'ready', + finishes: 1, + last: unsaved, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 500 }, + outcome: 'ok', + }, + ], + [ + 'restored', + 'settledStop', + { + status: 'ready', + finishes: 1, + last: settled, + action: NONE, + abort: { streamId: 'convo-1', generationCreatedAt: 500 }, + outcome: 'ok', + }, + ], ['detached', 'reconnectIdle', { status: 'ready', finishes: 2, last: settled, abort: NONE }], + /** The reconnect named generation 100, older than the restored pause's 500, so it is stale. */ + ['restored', 'reconnectIdle', { status: 'ready', finishes: 0, action: 'action-1', abort: NONE }], ['aborted', 'reconnectIdle', { status: 'ready', finishes: 1, last: aborted, abort: NONE }], [ 'detached', @@ -667,6 +802,7 @@ const table: Array<[keyof typeof states, keyof typeof events, Expected]> = [ ]; const live = { streamId: 'convo-1', generationCreatedAt: 100 }; +const restoredTarget = { streamId: 'convo-1', generationCreatedAt: 500 }; /** * Dispose, stop and a late server answer, across every phase a turn can be in: before its start is @@ -782,6 +918,69 @@ const teardown: Array<[keyof typeof states, keyof typeof events, Expected]> = [ outcome: 'disposed', }, ], + + [ + 'paused', + 'dispose', + { status: 'streaming', connection: 'idle', finishes: 0, turn: 'settled', abort: NONE }, + ], + [ + 'paused', + 'lateAnswer', + { + status: 'ready', + connection: 'idle', + finishes: 1, + last: aborted, + action: NONE, + turn: 'settled', + abort: live, + outcome: 'ok', + after: 'idle', + }, + ], + [ + 'paused', + 'disposeDuringStop', + { + status: 'streaming', + connection: 'idle', + finishes: 0, + turn: 'settled', + abort: live, + outcome: 'disposed', + }, + ], + + [ + 'restored', + 'dispose', + { status: 'ready', connection: 'idle', finishes: 0, action: 'action-1', abort: NONE }, + ], + [ + 'restored', + 'lateAnswer', + { + status: 'ready', + finishes: 1, + last: stoppedUnframed, + action: NONE, + abort: restoredTarget, + outcome: 'ok', + after: 'idle', + }, + ], + [ + 'restored', + 'disposeDuringStop', + { + status: 'ready', + connection: 'idle', + finishes: 0, + abort: restoredTarget, + outcome: 'disposed', + }, + ], ]; /** A stop that finds the generation already gone ends whatever the chat still held for it. */ @@ -804,6 +1003,31 @@ const gone: Array<[keyof typeof states, keyof typeof events, Expected]> = [ 'goneStop', { status: 'ready', finishes: 2, last: settled, abort: live, outcome: 'ok' }, ], + [ + 'paused', + 'goneStop', + { + status: 'ready', + connection: 'idle', + finishes: 1, + last: settled, + action: NONE, + abort: live, + outcome: 'ok', + }, + ], + [ + 'restored', + 'goneStop', + { + status: 'ready', + finishes: 1, + last: settled, + action: NONE, + abort: restoredTarget, + outcome: 'ok', + }, + ], ]; describe('Chat teardown', () => { @@ -826,6 +1050,9 @@ describe('Chat teardown', () => { expect(h.transport.abort).toHaveBeenCalledTimes(1); expect(h.transport.abort).toHaveBeenCalledWith(expect.objectContaining(expected.abort)); } + if (expected.action !== undefined) { + expect(h.chat.pendingAction?.actionId ?? null).toBe(expected.action); + } if (expected.outcome !== undefined) { expect(h.outcome).toContain(expected.outcome); } @@ -861,6 +1088,9 @@ describe('Chat lifecycle', () => { expect(h.transport.abort).toHaveBeenCalledTimes(1); expect(h.transport.abort).toHaveBeenCalledWith(expect.objectContaining(expected.abort)); } + if (expected.action !== undefined) { + expect(h.chat.pendingAction?.actionId ?? null).toBe(expected.action); + } if (expected.outcome !== undefined) { expect(h.outcome).toContain(expected.outcome); } @@ -884,6 +1114,8 @@ const disposedCalls: Record Promise> = { stop: (h) => h.chat.stop(), resumeStream: (h) => h.chat.resumeStream({ streamId: 'convo-1' }), sendMessage: (h) => h.chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }), + answer: (h) => h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }), + restore: async (h) => h.chat.restorePendingAction({ ...askAction, actionId: 'action-9' }, 600), }; const transportCalls = (h: Harness) => @@ -898,6 +1130,7 @@ const disposedTable = Object.keys(withLost).flatMap((state) => Object.keys(disposedCalls).map((call) => [state, call] as const), ); +const restoredResponse: TMessage = { ...placeholder, messageId: 'response-9', text: 'Paused' }; const laterMessage: TMessage = { ...placeholder, messageId: 'response-10', text: 'Later' }; describe('Chat invariants', () => { @@ -1060,6 +1293,22 @@ describe('Chat invariants', () => { }, ); + it('(1) a stop of a restored pause ends the pause a refresh restored for its generation meanwhile', async () => { + const h = createHarness(); + let answerStop: (() => void) | undefined; + h.transport.abort.mockImplementation( + () => new Promise((resolve) => (answerStop = () => resolve({ success: true }))), + ); + h.chat.restorePendingAction(askAction, 500); + const stopped = h.chat.stop(); + await flush(); + h.chat.restorePendingAction({ ...askAction, actionId: 'action-2' }, 500); + answerStop?.(); + await stopped; + + expect(h.chat.pendingAction).toBeUndefined(); + }); + it.each([ ['settled', { status: 'settled', conversationId: 'convo-1', generationProtocolVersion: 2 }], [ @@ -1092,7 +1341,10 @@ describe('Chat invariants', () => { }, ); - it.each([['a streamed frame', stepEvent]])( + it.each([ + ['a streamed frame', stepEvent], + ['a live pause', { type: 'pending_action', data: askAction } as ChatEvent], + ])( "(4) a reattachment that recovers with %s ends the dropped connection's error", async (_label, event) => { const h = createHarness(); @@ -1161,6 +1413,45 @@ describe('Chat invariants', () => { expect(h.finishes).toHaveLength(1); expect(h.finishes[0]).toMatchObject({ isResponseUnknown: true, message: undefined }); }); + + it.each([ + ['named by the status read', 'response-9', false], + ['the status read did not name', undefined, true], + ])( + '(4) an unframed stop of a restored pause reports the response %s', + async (_label, responseMessageId, unknown) => { + const h = createHarness({ messages: [userMessage, restoredResponse, laterMessage] }); + h.transport.abort.mockResolvedValue({ + success: true, + generationProtocolVersion: 2, + aborted: 'convo-1', + persistenceFailed: true, + }); + h.chat.restorePendingAction({ ...askAction, responseMessageId }, 500); + + await h.chat.stop(); + + expect(h.finishes).toHaveLength(1); + expect(h.finishes[0]).toMatchObject({ isResponseUnknown: unknown }); + expect(h.finishes[0].message?.messageId).toBe(responseMessageId); + }, + ); + + it('(4) a stop of a reattachment ends the pause a later status read restored for its generation', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + h.chat.restorePendingAction({ ...askAction, actionId: 'action-2' }, 500); + h.transport.reconnectToStream.mockImplementation(() => new Promise(() => undefined)); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }).then( + () => undefined, + () => undefined, + ); + await flush(); + + await h.chat.stop(); + + expect(h.chat.pendingAction).toBeUndefined(); + }); }); /** Where a host callback or transport method can throw once a request owns the chat. */ @@ -1241,6 +1532,27 @@ describe('Chat exception safety', () => { ); }); + it('(5) a reattachment whose resume selection throws keeps a restored pause', async () => { + const f: Fault = { fault: false }; + const h = createHarness({ + resumeSelection: () => { + throwing(f, 'selection'); + return { endpoint: 'agents' }; + }, + }); + await states.restored(h); + f.fault = true; + + expect( + await settles(h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 })), + ).toBe(true); + expect(h.chat.pendingAction?.actionId).toBe('action-1'); + await h.chat.stop(); + expect(h.transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 500 }), + ); + }); + it('(5) a reattachment whose transport.reconnectToStream throws settles and frees the chat', async () => { const h = createHarness(); h.transport.reconnectToStream.mockImplementationOnce(() => { @@ -1282,6 +1594,110 @@ describe('Chat exception safety', () => { await h.chat.stop(); expect(h.transport.abort).toHaveBeenCalledTimes(2); }); + + it.each([ + ['resume selection throws', 'selection'], + ['transport.resume throws', 'resume'], + ])('(5) an answer whose %s keeps the pause answerable', async (_label, where) => { + const f: Fault = { fault: false }; + const h = createHarness({ + resumeSelection: () => { + if (where === 'selection') { + throwing(f, 'selection'); + } + return { endpoint: 'agents' }; + }, + }); + await states.restored(h); + f.fault = true; + if (where === 'resume') { + f.fault = false; + h.transport.resume.mockImplementationOnce(() => { + throw new Error('resume failed'); + }); + } + + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + expect(h.chat.pendingAction?.actionId).toBe('action-1'); + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + expect(h.transport.resume).toHaveBeenCalledTimes(where === 'resume' ? 2 : 1); + }); + + it('(5) a continuation runs on the selection its answer read, so a host that throws later strands nothing', async () => { + let calls = 0; + const onError = jest.fn(); + const h = createHarness({ + onError, + resumeSelection: () => { + calls += 1; + if (calls > 1) { + throw new Error('selection failed'); + } + return { endpoint: 'agents' }; + }, + }); + const continued = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(continued); + const unhandled = jest.fn(); + process.on('unhandledRejection', unhandled); + try { + await states.restored(h); + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + await flush(); + expect(unhandled).not.toHaveBeenCalled(); + expect(h.transport.reconnectToStream).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 500 }), + ); + h.transport.abort.mockResolvedValueOnce({ success: true }); + continued.push(stepEvent); + await flush(); + const stopped = h.chat.stop(); + continued.push(finalEvent({ terminalStatus: 'aborted' })); + await stopped; + expect(h.transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ endpoint: 'agents', generationCreatedAt: 500 }), + ); + expect(onError).not.toHaveBeenCalled(); + } finally { + process.off('unhandledRejection', unhandled); + } + }); +}); + +describe('Chat markers kept until a start is accepted', () => { + it.each([ + ['whose preparation fails', 'prepare'], + ['that loses its response', 'network'], + ])( + '(2) a retry %s keeps the resumed pause of the live generation stale', + async (_label, where) => { + const h = createHarness({ + prepareRequest: () => { + if (where === 'prepare') { + return Promise.reject(new Error('Upload failed')) as never; + } + return { payload, messages: [userMessage, placeholder], responseMessageId: 'response-1' }; + }, + }); + await states.restored(h); + const continued = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(continued); + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + await flush(); + continued.push(stepEvent); + await flush(); + continued.push(dropEvent); + await flush(); + if (where === 'network') { + h.transport.sendMessages.mockRejectedValueOnce(networkError()); + } + send(h); + await flush(); + + h.chat.restorePendingAction(askAction, 500); + expect(h.chat.pendingAction).toBeUndefined(); + }, + ); }); describe('Chat stops the server answers as already settled', () => { @@ -1340,6 +1756,32 @@ describe('Chat final frames', () => { }); }); +describe('Chat status reads and lost starts', () => { + it("(2) a status read never takes over a lost start; a stop ends the pause and still owes the start's abort", async () => { + const h = createHarness(); + await lost(h); + h.chat.restorePendingAction(askAction, 500); + + await expect(h.chat.stop()).resolves.toEqual({ status: 'unaddressable' }); + expect(h.transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 500 }), + ); + expect(h.chat.pendingAction).toBeUndefined(); + }); + + it('(2) a status read older than the dropped generation is stale and keeps it the stop target', async () => { + const h = createHarness(); + await states.detached(h); + h.chat.restorePendingAction(askAction, 50); + + expect(h.chat.pendingAction).toBeUndefined(); + await h.chat.stop(); + expect(h.transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 100 }), + ); + }); +}); + const createdUnder = 'convo-9'; const learns: Array<[string, (h: Harness) => Promise]> = [ [ @@ -1384,6 +1826,14 @@ const learns: Array<[string, (h: Harness) => Promise]> = [ await flush(); }, ], + [ + 'a status read', + async (h) => { + h.chat.restorePendingAction({ ...askAction, conversationId: createdUnder }, 500); + h.transport.abort.mockResolvedValueOnce({ success: true }); + await h.chat.stop(); + }, + ], ]; describe('Chat conversation identity', () => { @@ -1428,7 +1878,22 @@ describe('Chat conversation identity', () => { }); describe('Chat status reads out of order', () => { - it.each([['the dropped generation', states.detached, 50, 100]])( + it('(2) a status read older than the restored pause is stale and keeps the newer pause', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + h.chat.restorePendingAction({ ...askAction, actionId: 'action-old' }, 400); + + expect(h.chat.pendingAction?.actionId).toBe('action-1'); + await h.chat.stop(); + expect(h.transport.abort).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 500 }), + ); + }); + + it.each([ + ['the restored pause', states.restored, 400, 500], + ['the dropped generation', states.detached, 50, 100], + ])( '(2) a reattachment naming a generation older than %s changes nothing', async (_label, state, named, kept) => { const h = createHarness(); @@ -1445,6 +1910,16 @@ describe('Chat status reads out of order', () => { }, ); + it('(2) a status read older than a generation that already finished is stale', async () => { + const h = createHarness(); + await states.attached(h); + h.stream?.push(finalEvent()); + await flush(); + + h.chat.restorePendingAction(askAction, 50); + expect(h.chat.pendingAction).toBeUndefined(); + }); + it('(5) an idle stop answers idle without reading a resume selection that throws', async () => { const h = createHarness({ resumeSelection: () => { @@ -1457,6 +1932,46 @@ describe('Chat status reads out of order', () => { }); describe('Chat answers, successors and pause order', () => { + it('(7) an answer given while the stream stays attached carries its conversation into the next turn', async () => { + 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', + }; + }, + }); + h.transport.resume.mockResolvedValue({ + streamId: createdUnder, + conversationId: createdUnder, + status: 'resuming', + }); + const stream = createStream({ streamId: createdUnder, generationCreatedAt: 100 }); + attach(h, stream); + send(h); + await flush(); + stream.push({ + type: 'pending_action', + data: { ...askAction, conversationId: undefined }, + } as ChatEvent); + await flush(); + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + stream.push({ type: 'abort', data: {} } as ChatEvent); + await flush(); + + attach(h, createStream({ streamId: createdUnder, generationCreatedAt: 200 })); + send(h); + await flush(); + expect(prepared[prepared.length - 1]).toBe(createdUnder); + expect(h.transport.sendMessages).toHaveBeenLastCalledWith( + expect.objectContaining({ chatId: createdUnder }), + ); + }); + it('(2) a stop of an unsent retry still ends the dropped generation when its callback starts a successor', async () => { let prepared = 0; let started = false; @@ -1490,11 +2005,81 @@ describe('Chat answers, successors and pause order', () => { expect.objectContaining({ generationCreatedAt: 100 }), ); }); + + it.each(['ERR_NETWORK', 'ERR_INTERNET_DISCONNECTED'])( + '(2) an answer that fails on the network (%s) reattaches to the paused generation', + async (code) => { + const h = createHarness(); + await states.restored(h); + h.transport.resume.mockRejectedValueOnce(Object.assign(new Error('Network Error'), { code })); + const continued = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(continued); + + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + await flush(); + expect(h.transport.reconnectToStream).toHaveBeenCalledWith( + expect.objectContaining({ generationCreatedAt: 500 }), + ); + continued.push(stepEvent); + await flush(); + expect(h.chat.status).toBe('streaming'); + h.transport.abort.mockResolvedValueOnce({ success: true }); + continued.push(finalEvent({ terminalStatus: 'aborted' })); + await flush(); + }, + ); + + it.each([ + ['refuses the caller', 403, {}], + ['is not ready for yet', 409, { code: 'EVENT_ACTOR_NOT_READY' }], + ])( + '(2) an answer the server %s keeps the pause answerable without reattaching', + async (_label, status, data) => { + const h = createHarness(); + await states.restored(h); + h.transport.resume.mockRejectedValueOnce( + Object.assign(new Error('Refused'), { response: { status, data, headers: {} } }), + ); + + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + await flush(); + expect(h.transport.reconnectToStream).not.toHaveBeenCalled(); + expect(h.chat.pendingAction?.actionId).toBe('action-1'); + }, + ); +}); + +describe('Chat sync snapshots and resume conflicts', () => { + it.each([ + ['a replaced run', 409, { code: 'RUN_REPLACED' }], + ['an action answered elsewhere', 409, { error: 'No live pending action to resume' }], + ['no paused generation', 404, { error: 'No paused generation for this conversation' }], + ])( + '(2) an answer refused for %s ends the pause and probes what runs now', + async (_label, status, data) => { + const h = createHarness(); + await states.restored(h); + h.transport.resume.mockRejectedValueOnce( + Object.assign(new Error('Conflict'), { response: { status, data, headers: {} } }), + ); + + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + await flush(); + expect(h.chat.pendingAction).toBeUndefined(); + expect(h.transport.reconnectToStream).toHaveBeenCalledTimes(1); + await expect(freeAfter(h)).resolves.toBe(true); + }, + ); }); describe('Chat identity every frame carries', () => { const ids = { conversationId: createdUnder, responseMessageId: 'response-9' }; const frames: Array<[string, ChatEvent, { response?: boolean; conversation?: boolean }]> = [ + [ + 'pending_action', + { type: 'pending_action', data: { ...askAction, ...ids } } as ChatEvent, + { response: true, conversation: true }, + ], [ 'activity_label', { type: 'activity_label', data: { index: 0, part: {}, ...ids } } as unknown as ChatEvent, @@ -1656,7 +2241,89 @@ describe('Chat late answers and lost starts', () => { ); }); +describe('Chat retries that continue an answered generation', () => { + it.each([ + ['a stream', 'stream'], + ['a replacement', 'replaced'], + ])( + '(2) a retry answered with %s of the dropped generation keeps its answered pause stale', + async (_label, kind) => { + const h = createHarness(); + await states.restored(h); + const continued = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(continued); + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + await flush(); + continued.push(stepEvent); + await flush(); + continued.push(dropEvent); + await flush(); + + const retry = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + if (kind === 'stream') { + h.transport.sendMessages.mockResolvedValueOnce({ status: 'stream', stream: retry }); + } else { + h.transport.sendMessages.mockResolvedValueOnce({ + status: 'replaced', + conversationId: 'convo-1', + streamId: 'convo-1', + generationCreatedAt: 500, + generationProtocolVersion: 2, + }); + h.transport.reconnectToStream.mockResolvedValueOnce(retry); + } + send(h); + await flush(); + retry.push({ type: 'pending_action', data: askAction } as ChatEvent); + await flush(); + + expect(h.chat.pendingAction).toBeUndefined(); + }, + ); +}); + +describe('Chat status reads of a dropped generation', () => { + it('(4) a status read naming the response of the dropped generation reaches its unframed stop', async () => { + const named: TMessage = { ...placeholder, messageId: 'response-9', text: 'Named' }; + const h = createHarness({ + messages: [userMessage, named, { ...placeholder, messageId: 'other' }], + }); + const stream = createStream({ streamId: 'convo-1', generationCreatedAt: 700 }); + h.transport.reconnectToStream.mockResolvedValueOnce(stream); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 700 }).then( + () => undefined, + () => undefined, + ); + await flush(); + stream.push(dropEvent); + await flush(); + h.chat.restorePendingAction({ ...askAction, responseMessageId: 'response-9' }, 700); + h.transport.abort.mockResolvedValueOnce({ + success: true, + generationProtocolVersion: 2, + aborted: 'convo-1', + persistenceFailed: true, + }); + + await h.chat.stop(); + + const last = h.finishes[h.finishes.length - 1]; + expect(last).toMatchObject({ isResponseUnknown: false }); + expect(last.message?.messageId).toBe('response-9'); + }); +}); + describe('Chat stops while a lost start is owed', () => { + it('(2) a stop of a restored pause keeps the failure a lost start reported', async () => { + const h = createHarness(); + await lost(h); + expect(h.chat.status).toBe('error'); + h.chat.restorePendingAction(askAction, 500); + + await expect(h.chat.stop()).resolves.toEqual({ status: 'unaddressable' }); + expect(h.chat.status).toBe('error'); + }); + it('(2) a stop of a reattachment still owes the lost start', async () => { const h = createHarness(); await lost(h); @@ -1705,6 +2372,62 @@ describe('Chat reattachments that fail over HTTP', () => { }); }); +describe('Chat unframed stops while a lost start is owed', () => { + it.each([ + [ + 'settled', + { success: false, settled: true, terminalStatus: 'complete', generationProtocolVersion: 2 }, + ], + [ + 'persistence failed', + { success: true, aborted: 'convo-1', persistenceFailed: true, generationProtocolVersion: 2 }, + ], + ['gone', Object.assign(new Error('Not Found'), { response: { status: 404 } })], + ])('(2) a %s stop of a restored pause keeps the lost start failure', async (_label, answer) => { + const h = createHarness(); + await lost(h); + const failure = h.chat.error; + h.chat.restorePendingAction(askAction, 500); + if (answer instanceof Error) { + h.transport.abort.mockRejectedValueOnce(answer); + } else { + h.transport.abort.mockResolvedValueOnce(answer as ChatAbortResult); + } + + await expect(h.chat.stop()).resolves.toEqual({ status: 'unaddressable' }); + expect(h.chat.status).toBe('error'); + expect(h.chat.error).toBe(failure); + }); +}); + +describe('Chat resume conflicts after a newer pause', () => { + it('(1) a conflict for an answered pause leaves a newer pause restored meanwhile', async () => { + const h = createHarness(); + await states.restored(h); + let refuse: (() => void) | undefined; + h.transport.resume.mockImplementationOnce( + () => + new Promise((_resolve, reject) => { + refuse = () => + reject( + Object.assign(new Error('Conflict'), { + response: { status: 409, data: { code: 'RUN_REPLACED' }, headers: {} }, + }), + ); + }), + ); + const answered = h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }); + await flush(); + h.chat.restorePendingAction({ ...askAction, actionId: 'action-newer', createdAt: 9 }, 600); + refuse?.(); + await answered.catch(() => undefined); + await flush(); + + expect(h.chat.pendingAction?.actionId).toBe('action-newer'); + expect(h.transport.reconnectToStream).not.toHaveBeenCalled(); + }); +}); + describe('Chat lost starts and conflict probes', () => { it('(2) a retry stopped before it is sent keeps the lost start failure', async () => { let prepared = 0; @@ -1725,6 +2448,33 @@ describe('Chat lost starts and conflict probes', () => { expect(h.chat.status).toBe('error'); expect(h.chat.error).toBeDefined(); }); + + it('(1) a resume conflict probes before a subscriber can take the chat, and settles the pause it finds ended', async () => { + const h = createHarness(); + await states.restored(h); + h.transport.resume.mockRejectedValueOnce( + Object.assign(new Error('Conflict'), { + response: { status: 409, data: { error: 'No live pending action to resume' }, headers: {} }, + }), + ); + let raced = false; + const unsubscribe = h.chat.subscribe(() => { + if (!raced && !h.chat.pendingAction && h.chat.status === 'ready') { + raced = true; + h.chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] }).then( + () => undefined, + () => undefined, + ); + } + }); + + await h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' }).catch(() => undefined); + await flush(); + unsubscribe(); + + expect(h.transport.reconnectToStream).toHaveBeenCalledTimes(1); + expect(h.finishes[0]).toMatchObject({ isSettled: true }); + }); }); describe('Chat disposed while a confirmed stop ends its request', () => { @@ -1972,6 +2722,14 @@ const stopExits: Array<[string, (h: Harness) => Promise, StopExit]> = [ }, { last: settled, outcome: 'ok' }, ], + [ + 'restored pause: the pause a status read restored is stopped', + async (h) => { + await states.restored(h); + await events.stop(h); + }, + { last: stoppedUnframed, outcome: 'ok' }, + ], [ 'never answered: the start lost its response, so the stop cannot name it', async (h) => { @@ -2024,6 +2782,130 @@ describe('Chat stop exits and the reload signal', () => { }); }); +/** Table 1: every pause transition, the pause it leaves held, and the decisions it keeps. */ +describe('Chat pause lifecycle and its decision markers', () => { + const approval = { + ...askAction, + payload: { + type: 'tool_approval', + action_requests: [{ tool_call_id: 'tool-1' }, { tool_call_id: 'tool-2' }], + }, + } as unknown as Agents.PendingAction; + const reattached = async (h: Harness) => { + const stream = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(stream); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }).then( + () => undefined, + () => undefined, + ); + await flush(); + return stream; + }; + const answerFails = (h: Harness, error: Error) => h.transport.resume.mockRejectedValueOnce(error); + const answerSecond = async (h: Harness) => { + await h.chat.addToolApprovalResponse({ id: 'tool-2', approved: true }).catch(() => undefined); + await flush(); + }; + + type PauseRow = { + /** The pause held after the transition, or `null` when none is. */ + held: string | null; + /** + * Decisions the next resume carries once the second call is answered: 2 when the first + * call's decision was kept, 0 when it was cleared and no resume is sent. Omitted when no pause + * is left to answer. + */ + submitted?: number; + }; + + const rows: Array<[string, (h: Harness) => Promise, PauseRow]> = [ + [ + 'a status read restores the held pause again', + async (h) => h.chat.restorePendingAction({ ...approval }, 500), + { held: 'action-1', submitted: 2 }, + ], + [ + 'the stream replays the held pause', + async (h) => { + const stream = await reattached(h); + stream.push({ type: 'pending_action', data: approval } as ChatEvent); + await flush(); + }, + { held: 'action-1', submitted: 2 }, + ], + [ + 'the answer is accepted, and a status read of that pause comes late', + async (h) => { + await answerSecond(h); + h.chat.restorePendingAction({ ...approval }, 500); + }, + { held: null }, + ], + [ + 'the answer is lost on the network', + async (h) => { + answerFails(h, networkError()); + await answerSecond(h); + }, + { held: null }, + ], + [ + 'the answer is refused because the pause is over (409)', + async (h) => { + answerFails( + h, + Object.assign(new Error('Conflict'), { + response: { status: 409, data: { code: 'RUN_REPLACED' }, headers: {} }, + }), + ); + await answerSecond(h); + }, + { held: null }, + ], + [ + 'the answer is refused because the server is not ready yet', + async (h) => { + answerFails( + h, + Object.assign(new Error('Not ready'), { + response: { status: 409, data: { code: 'EVENT_ACTOR_NOT_READY' }, headers: {} }, + }), + ); + await answerSecond(h); + }, + { held: 'action-1', submitted: 2 }, + ], + [ + 'the held pause is stopped', + async (h) => { + await h.chat.stop(); + await flush(); + }, + { held: null }, + ], + ]; + + it.each(rows)('%s', async (_transition, drive, expected) => { + const h = createHarness(); + h.chat.restorePendingAction(approval, 500); + await h.chat.addToolApprovalResponse({ id: 'tool-1', approved: true }); + await drive(h); + + expect(h.chat.pendingAction?.actionId ?? null).toBe(expected.held); + if (expected.submitted === undefined) { + return; + } + const before = h.transport.resume.mock.calls.length; + h.transport.resume.mockClear(); + await answerSecond(h); + const calls = h.transport.resume.mock.calls as unknown as Array<[{ decisions?: unknown[] }]>; + expect(calls.length > 0 ? (calls[calls.length - 1][0].decisions?.length ?? 0) : 0).toBe( + expected.submitted, + ); + expect(before).toBeGreaterThanOrEqual(0); + }); +}); + /** Table 2: every path a lost start can take, and what a stop answers after it. */ describe('Chat lost-start resolution', () => { const lose = async (h: Harness) => { @@ -2052,6 +2934,12 @@ describe('Chat lost-start resolution', () => { }, 'unaddressable', ], + [ + 'a status read that restores a pause', + 'convo-1', + async (h) => h.chat.restorePendingAction(askAction, 500), + 'unaddressable', + ], ['the chat is disposed', 'convo-1', async (h) => h.chat.dispose(), 'idle'], ]; @@ -2118,6 +3006,34 @@ describe('Chat notify ordering and request ownership', () => { expect(h.transport.sendMessages).toHaveBeenCalledTimes(1); }); + it('an answer sends nothing when the host disposes the chat while it selects the endpoint', async () => { + const h = createHarness({ + resumeSelection: () => { + h.chat.dispose(); + return { endpoint: 'agents' }; + }, + }); + h.chat.restorePendingAction(askAction, 500); + + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow( + 'disposed', + ); + expect(h.transport.resume).not.toHaveBeenCalled(); + }); + + it('a reattachment owns the chat before it clears a pause it supersedes', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + h.transport.reconnectToStream.mockImplementation(() => new Promise(() => undefined)); + const { attempt, unsubscribe } = startOnNotify(h, () => !h.chat.pendingAction); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 900 }).catch(() => undefined); + await flush(); + unsubscribe(); + + expect(attempt.error).toContain('already in flight'); + expect(h.transport.sendMessages).not.toHaveBeenCalled(); + }); + it('a streamed frame notifies while the request still owns the chat', async () => { const h = createHarness(); attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 100 })); @@ -2147,6 +3063,40 @@ describe('Chat notify ordering and request ownership', () => { expect(h.transport.sendMessages).toHaveBeenCalledTimes(2); }); + it('an approval write notifies after the pause is held, so a second answer sends one resume', async () => { + const approval = { + ...askAction, + payload: { + type: 'tool_approval', + action_requests: [{ tool_call_id: 'tool-1' }, { tool_call_id: 'tool-2' }], + }, + } as unknown as Agents.PendingAction; + const h = createHarness({ messages: [userMessage, placeholder] }); + h.chat.restorePendingAction(approval, 500); + await h.chat.addToolApprovalResponse({ id: 'tool-1', approved: true }); + let answered: Promise | undefined; + const unsubscribe = h.chat.subscribe(() => { + answered ??= h.chat.addToolApprovalResponse({ id: 'tool-2', approved: true }); + }); + await h.chat.addToolApprovalResponse({ id: 'tool-2', approved: true }).catch(() => undefined); + await answered?.catch(() => undefined); + await flush(); + unsubscribe(); + + expect(h.transport.resume).toHaveBeenCalledTimes(1); + }); + + it('a status read that restores a pause notifies with the pause held, which blocks a turn', async () => { + const h = createHarness(); + const { attempt, unsubscribe } = startOnNotify(h, () => true); + h.chat.restorePendingAction(askAction, 500); + await flush(); + unsubscribe(); + + expect(attempt.error).toContain('waiting for a decision'); + expect(h.transport.sendMessages).not.toHaveBeenCalled(); + }); + it('a stop of a dropped generation notifies after it let the chat go, so the next turn owns it', async () => { const h = createHarness(); await states.detached(h); @@ -2626,6 +3576,43 @@ describe('Chat dropped generations a retry, a stop or a status read settles', () }); }); +describe('Chat pauses a stop that outlives a failed reconnect ends', () => { + it('the restored pause ends with the dropped generation the stop answer ends', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + let fail: (() => void) | undefined; + h.transport.reconnectToStream.mockImplementationOnce( + () => + new Promise((_resolve, reject) => { + fail = () => reject(networkError()); + }), + ); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }).then( + () => undefined, + () => undefined, + ); + await flush(); + let answerStop: (() => void) | undefined; + h.transport.abort.mockImplementationOnce( + () => + new Promise((resolve) => { + answerStop = () => resolve({ success: true, aborted: 'convo-1' }); + }), + ); + const stopping = h.chat.stop(); + await flush(); + fail?.(); + await flush(); + expect(h.chat.pendingAction?.actionId).toBe('action-1'); + answerStop?.(); + await stopping; + await flush(); + + expect(h.chat.pendingAction).toBeUndefined(); + expect((await h.chat.stop()).status).toBe('idle'); + }); +}); + /** A store that reports each field it is written, as a cache another hook also writes does. */ const createReportingState = (): ChatState => { const listeners = new Set<() => void>(); @@ -2762,3 +3749,49 @@ describe('Chat reconnects that settle a dropped generation or a lost start', () expect(h.chat.status).toBe('ready'); }); }); + +describe('Chat pauses the server refused to resume', () => { + it('a refused pause stays retired when the probe that follows it fails on the network', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + h.transport.resume.mockRejectedValueOnce( + Object.assign(new Error('gone'), { response: { status: 404 } }), + ); + h.transport.reconnectToStream.mockRejectedValueOnce(networkError()); + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + await flush(); + + expect(h.chat.pendingAction).toBeUndefined(); + attach(h, createStream({ streamId: 'convo-1', generationCreatedAt: 600 })); + let refused: unknown; + h.chat.sendMessage({ parts: [{ type: 'text', text: 'Next' }] }).catch((error: unknown) => { + refused = error; + }); + await flush(); + expect(refused).toBeUndefined(); + }); + + it('a refused pause stays over for a later status read and a reattached replay', async () => { + const h = createHarness(); + h.chat.restorePendingAction(askAction, 500); + h.transport.resume.mockRejectedValueOnce( + Object.assign(new Error('gone'), { response: { status: 404 } }), + ); + h.transport.reconnectToStream.mockRejectedValueOnce(networkError()); + await expect(h.chat.addToolOutput({ toolCallId: 'ask-1', output: 'A' })).rejects.toThrow(); + await flush(); + + h.chat.restorePendingAction(askAction, 500); + expect(h.chat.pendingAction).toBeUndefined(); + const stream = createStream({ streamId: 'convo-1', generationCreatedAt: 500 }); + h.transport.reconnectToStream.mockResolvedValueOnce(stream); + h.chat.resumeStream({ streamId: 'convo-1', generationCreatedAt: 500 }).then( + () => undefined, + () => undefined, + ); + await flush(); + stream.push({ type: 'pending_action', data: askAction } as unknown as ChatEvent); + await flush(); + expect(h.chat.pendingAction).toBeUndefined(); + }); +}); diff --git a/packages/chat/src/core/chat.ts b/packages/chat/src/core/chat.ts index dfb883a699..977f76984f 100644 --- a/packages/chat/src/core/chat.ts +++ b/packages/chat/src/core/chat.ts @@ -1,5 +1,6 @@ -import { Constants } from 'librechat-data-provider'; +import { Constants, ContentTypes } from 'librechat-data-provider'; import type { + Agents, TPayload, TMessage, ChatEvent, @@ -7,6 +8,7 @@ import type { TPendingSteer, ChatFinalFrame, ChatErrorData, + TMessageContentParts, UIMessageMetadata, } from 'librechat-data-provider'; import type { @@ -148,7 +150,7 @@ export type ChatInit = { * response messages are merged into the list by id and every other event only moves the status. */ applyEvent?(event: ChatEvent, context: ChatEventContext): void; - /** The agent selection a generation this chat did not start runs on, which a reattachment reads. */ + /** The agent selection a paused generation resumes with, matching the request that started it. */ resumeSelection?(): Omit; onError?(error: Error): void; onFinish?(result: ChatFinishResult): void; @@ -156,6 +158,25 @@ export type ChatInit = { onEvent?(event: ChatEvent): void; }; +/** A tool call's review decision. AI SDK: `addToolApprovalResponse`. */ +export type ToolApprovalResponse = { + /** The paused tool call's id. */ + id: string; + approved: boolean; + reason?: string; + /** A decision other than approve or reject, such as `edit` or `respond`; it overrides `approved`. */ + decision?: Agents.ToolApprovalResolution['decision']; + editedArguments?: Agents.ToolApprovalResolution['editedArguments']; + responseText?: Agents.ToolApprovalResolution['responseText']; + scope?: Agents.ToolApprovalResolution['scope']; +}; + +/** The answer to an `ask_user_question` pause: free text, or answers keyed by question id. */ +export type ToolOutput = { + toolCallId: string; + output: string | Record; +}; + /** A turn whose messages the chat could not take from the stream, which the host reloads. */ type Settled = { conversationId?: string; @@ -187,6 +208,8 @@ type Generation = { * another generation) and no frame has named its response yet. */ responseUnknown?: boolean; + /** The pause this generation reported, which a confirmed stop ends. */ + paused?: string; /** 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. */ @@ -238,10 +261,10 @@ type ActiveRequest = { /** The generation this request runs or attaches to. */ generation: Generation; /** - * Set when reattaching to a generation already running on the server, before it attaches, - * naming the stream a stop addresses meanwhile. + * Set when reattaching to a generation already running on the server, before it attaches. + * `continuation` marks one whose pause was answered meanwhile, so finding nothing means it ended. */ - reattach?: { streamId?: string }; + reattach?: { streamId?: string; continuation?: boolean }; /** * The stream came from attaching to a running generation, whose HTTP failure ends only the * attachment unless the server says the generation is gone. @@ -363,6 +386,20 @@ const getApplyFailure = (event: ChatEvent, failure: unknown, attached: boolean): : { kind: 'error', error, disconnect: true }; }; +/** + * A resume the server refused because the pause is over: no paused generation (404), or a conflict + * (409) such as a replaced run or an action answered elsewhere. A 409 that only says the event + * actor is not ready yet leaves the pause answerable for a retry. + */ +const isPauseOver = (error: ChatTransportError): boolean => { + const status = error.response?.status; + if (status === 404) { + return true; + } + const code = (error.response?.data as { code?: string } | undefined)?.code; + return status === 409 && code !== 'EVENT_ACTOR_NOT_READY'; +}; + /** A run that ended on its own before a stop reached it, whose final frame never arrived. */ const getSettledOutcome = ( status: ChatStreamAbortResult['terminalStatus'], @@ -545,6 +582,81 @@ const defaultApplyEvent = (event: ChatEvent, context: ChatEventContext) => { } }; +/** A tool call that may hold a subagent's own tool calls, where a paused tool can live. */ +type NestedToolCall = Agents.ToolCall & { subagent_content?: TMessageContentParts[] }; + +/** + * Writes `decision` onto the tool calls of `actionId` with the given id in `parts`, descending into + * subagent calls the way the pause was tagged. Returns the new parts, or nothing when none matched. + */ +const markApprovalIn = ( + parts: TMessageContentParts[], + actionId: string, + toolCallId: string, + decision: Agents.ToolApprovalResolution, +): TMessageContentParts[] | undefined => { + let next: TMessageContentParts[] | undefined; + parts.forEach((part, index) => { + if (part?.type !== ContentTypes.TOOL_CALL) { + return; + } + const toolCall = part.tool_call as NestedToolCall | undefined; + if (!toolCall) { + return; + } + let marked = toolCall; + const nested = Array.isArray(toolCall.subagent_content) + ? markApprovalIn(toolCall.subagent_content, actionId, toolCallId, decision) + : undefined; + if (nested) { + marked = { ...marked, subagent_content: nested }; + } + if ( + 'approval' in toolCall && + toolCall.id === toolCallId && + toolCall.approval?.actionId === actionId + ) { + const approval = { + ...toolCall.approval, + decision: decision.decision, + reason: decision.reason, + }; + if (decision.reason === undefined) { + /** A changed decision shows only its own reason. */ + delete approval.reason; + } + marked = { ...marked, approval }; + } + if (marked === toolCall) { + return; + } + next ??= [...parts]; + next[index] = { ...part, tool_call: marked } as TMessageContentParts; + }); + return next; +}; + +/** Writes `decision` onto every tool call of `actionId` with the given id. */ +const markApproval = ( + messages: TMessage[], + actionId: string, + toolCallId: string, + decision: Agents.ToolApprovalResolution, +): TMessage[] | undefined => { + let changed = false; + const next = messages.map((message) => { + const content = message.content + ? markApprovalIn(message.content, actionId, toolCallId, decision) + : undefined; + if (!content) { + return message; + } + changed = true; + return { ...message, content }; + }); + return changed ? next : undefined; +}; + /** * Where a removed row goes back: after the nearest earlier row of `before` still listed, else * before the nearest later one, so rows written around it since then keep their place. @@ -684,7 +796,11 @@ export class Chat { private readonly listeners = new Set<() => void>(); private releaseState?: () => void; private active?: ActiveRequest; + /** The pause the running generation waits on, for a tool decision or an answer. */ + private action?: Agents.PendingAction; private generationCreatedAt?: number; + /** The pause whose resume request is in flight, so a second submit cannot send it again. */ + private resuming?: string; private disposed = false; /** Set while the chat writes the state, whose own report of that write the chat announces itself. */ private writing = false; @@ -693,8 +809,15 @@ export class Chat { private readonly lifetime = new AbortController(); /** A generation whose stream dropped while the server kept it running. */ private detached?: DetachedGeneration; - /** The timestamps of the generations a stop or their own stream ended. */ + /** The timestamps of the generations a stop or their own stream ended, whose later pauses are stale. */ private readonly endedGenerations = new Set(); + /** The generation a restored pause belongs to, which a reattachment to it continues. */ + private restored?: { createdAt: number; generation: Generation }; + private readonly decisions = new Map(); + /** Pauses already resumed, or refused as over, whose replay or later status read is stale. */ + private readonly resumed = new Set(); + /** The newest generation a status read named, below which a read is stale. */ + private newestRead?: number; /** The newest start handed to the transport, whose conversation a late answer must not replace. */ private latestStart?: ActiveRequest; /** @@ -757,6 +880,11 @@ export class Chat { }); } + /** The pause the running generation waits on for a tool decision or an answer, if any. */ + get pendingAction(): Agents.PendingAction | undefined { + return this.action; + } + /** Submits a user turn. Rejects while another turn of this chat is in flight. */ sendMessage(input: SendMessageInput, options?: ChatRequestOptions): Promise { return this.request({ trigger: 'submit-message', input }, options); @@ -778,18 +906,43 @@ export class Chat { * Reattaches to the generation the server is still running. The status stays as it is until a * stream is returned, so a chat with nothing running never flashes `submitted`. */ - async resumeStream( + resumeStream( options: { streamId?: string; generationCreatedAt?: number } & ChatRequestOptions = {}, + ): Promise { + return this.reattach(options, false); + } + + /** + * Reattaches to a running generation. A `continuation` follows an answered pause, so finding + * nothing running means the continuation already finished, which the turn reports as settled. + */ + private async reattach( + options: { + streamId?: string; + generationCreatedAt?: number; + /** The conversation the generation runs under, when the server named it. */ + conversationId?: string; + /** The endpoint an answer already resolved, so its continuation does not ask the host again. */ + endpoint?: string; + /** A pause the server refused to resume, retired once this reattachment owns the chat. */ + retire?: string; + } & ChatRequestOptions, + continuation: boolean, ): Promise { if (this.active || this.disposed) { return; } - if (options.generationCreatedAt != null && this.isStaleRead(options.generationCreatedAt)) { + if ( + options.generationCreatedAt != null && + !continuation && + this.isStaleRead(options.generationCreatedAt) + ) { /** A status read that named an older generation than this chat holds changes nothing. */ return; } /** The host's selection is read before any marker changes, so a throw leaves them all as they were. */ - const selected = this.resumeEndpoint(); + const { endpoint: resolved, retire, ...reattachOptions } = options; + const selected = resolved ?? this.resumeEndpoint(); if (this.active || this.disposed) { /** The host's selection may have started a turn or disposed the chat, which then owns it. */ return; @@ -806,7 +959,16 @@ export class Chat { options.generationCreatedAt === dropped?.target.generationCreatedAt ? dropped : undefined; - const active = createActiveRequest(continued?.generation); + /** Reattaching to a restored pause's generation continues its record the same way. */ + const paused = + !continued && + this.action && + (options.generationCreatedAt == null || + options.generationCreatedAt === this.restored?.createdAt) + ? this.restored + : undefined; + this.restored = undefined; + const active = createActiveRequest(continued?.generation ?? paused?.generation); const { generation } = active; if (!continued && generation.responseId === undefined) { /** @@ -817,16 +979,36 @@ export class Chat { } /** A continued generation runs where it started; the host's selection names any other. */ generation.endpoint = continued?.target.endpoint ?? selected ?? dropped?.target.endpoint; + generation.conversationId = options.conversationId ?? generation.conversationId; + this.learnConversation(options.conversationId); /** The generation the caller named, or the record continued, so a stream of another is told apart. */ active.inheritedGeneration = - options.generationCreatedAt ?? continued?.target.generationCreatedAt; + options.generationCreatedAt ?? continued?.target.generationCreatedAt ?? paused?.createdAt; active.reattach = { streamId: options.streamId ?? continued?.target.streamId }; active.attached = true; this.active = active; - /** Only the generation this continues vouches for a timestamp, so a stop made now addresses it. */ - this.generationCreatedAt = options.generationCreatedAt ?? active.inheritedGeneration; - const conversationId = generation.conversationId ?? this.conversationId; + const superseded = + this.action && + options.generationCreatedAt != null && + this.generationCreatedAt != null && + options.generationCreatedAt !== this.generationCreatedAt; + /** + * Only the generation this continues, or a restored pause, vouches for a timestamp. Stored + * before clearing a superseded pause notifies, so a stop made then addresses this generation. + */ + this.generationCreatedAt = + options.generationCreatedAt ?? + active.inheritedGeneration ?? + (this.action ? this.generationCreatedAt : undefined); + /** A restored pause names a running generation, so finding nothing means it ended elsewhere. */ + const restored = !superseded && this.action !== undefined; + const { conversationId = generation.conversationId ?? this.conversationId, ...request } = + reattachOptions; try { + if (superseded || (retire != null && this.action?.actionId === retire)) { + /** A restored pause belongs to the generation it was restored with, not this one. */ + this.clearAction(); + } this.setConnection('reconnecting'); if (active.controller.signal.aborted) { /** A listener of that notification stopped or disposed the chat; nothing is opened. */ @@ -834,7 +1016,7 @@ export class Chat { } const stream = await openUntilAborted( this.init.transport.reconnectToStream({ - ...options, + ...request, chatId: conversationId, resume: true, abortSignal: active.controller.signal, @@ -863,7 +1045,16 @@ export class Chat { options.generationCreatedAt != null && !this.endedGenerations.has(options.generationCreatedAt); /** A lost start the answer released may have finished on the server, which the host reloads. */ - if (!stream && (named || dropped != null || released)) { + const ended = + continuation || + restored || + named || + dropped != null || + released || + active.reattach.continuation; + if (!stream && ended) { + this.action = undefined; + this.decisions.clear(); this.settle({ kind: 'complete', settled: { conversationId } }, active); return; } @@ -909,9 +1100,12 @@ export class Chat { if (!active && this.detached) { return this.orUnaddressed(await this.stopDetached(this.detached)); } + if (!active && this.lostStart) { + /** A restored pause is stopped too, and the lost start is still the caller's. */ + return this.action ? this.orUnaddressed(await this.stopPaused()) : unaddressable; + } if (!active) { - /** The lost start is still the caller's. */ - return this.lostStart ? unaddressable : { status: 'idle' }; + return this.stopPaused(); } if (!active.stream && !active.reattach) { const { detached } = this; @@ -950,6 +1144,7 @@ export class Chat { if (!this.isAddressable(target)) { return unaddressable; } + generation.paused ??= this.action?.actionId; const result = await this.stopGeneration(generation, target); return this.orUnaddressed(await this.endStopped(active, generation, result)); } @@ -1039,6 +1234,8 @@ export class Chat { if (!this.active && this.detached?.generation === generation) { /** The request dropped before the answer arrived, so the answer ends what it left running. */ this.detached = undefined; + this.action = undefined; + this.decisions.clear(); if (this.publishUnframedStop(result, generation)) { return getStopResult(result, generation.stoppedConversationId); } @@ -1047,7 +1244,11 @@ export class Chat { if (active.disconnected && this.error === active.disconnected) { this.clearFailure(); } - this.notify(); + if (generation.paused && this.action?.actionId === generation.paused) { + this.clearAction(); + } else { + this.notify(); + } return getStopResult(result, generation.stoppedConversationId); } @@ -1279,6 +1480,8 @@ export class Chat { } const failed = this.detached?.error ?? detached.error; this.detached = undefined; + this.action = undefined; + this.decisions.clear(); if (this.publishUnframedStop(result, generation)) { return getStopResult(result, generation.stoppedConversationId); } @@ -1322,6 +1525,66 @@ export class Chat { return true; } + /** Stops a pause restored without a stream on the server, which frees the chat for a turn. */ + private async stopPaused(): Promise { + const action = this.action; + if (!action) { + return { status: 'idle' }; + } + const endpoint = this.resumeEndpoint(); + if (!endpoint) { + throw new Error('The paused generation cannot be stopped without its endpoint'); + } + const stoppedAt = this.generationCreatedAt; + /** A pause no status read restored names no response this chat prepared or saw framed. */ + const generation: Generation = this.restored?.generation ?? { responseUnknown: true }; + const result = await this.stopGeneration(generation, { + endpoint, + streamId: action.streamId, + generationCreatedAt: stoppedAt, + }); + const active = this.active; + if (!this.disposed && active?.generation === generation) { + /** A reattachment took the generation over while the stop was in flight; it ends with it. */ + return this.endStopped(active, generation, result); + } + /** Whatever pause the stopped generation holds now ends with it, however often it was refreshed. */ + const owned = + this.action && + (this.action.actionId === action.actionId || this.generationCreatedAt === stoppedAt); + if (this.disposed || !owned) { + return getStopResult(result, generation.stoppedConversationId); + } + this.action = undefined; + this.decisions.clear(); + /** A pause a status read restored names no response this chat prepared or saw framed. */ + const unframed = { + conversationId: generation.conversationId, + stoppedConversationId: generation.stoppedConversationId, + responseId: generation.responseId, + responseUnknown: generation.responseId === undefined, + }; + if (this.publishUnframedStop(result, unframed)) { + return getStopResult(result, generation.stoppedConversationId); + } + if (this.status === 'error' && !this.lostStart) { + /** + * The stop confirmed the end a dropped connection left unknown. A lost start still owed its + * own abort keeps the failure it reported. + */ + this.clearFailure(); + } + this.notify(); + return getStopResult(result, generation.stoppedConversationId); + } + + /** The conversation the paused generation's record names, which a frame may have assigned. */ + private pausedConversationId(): string | undefined { + const generation = + this.active?.generation ?? this.detached?.generation ?? this.restored?.generation; + return generation?.conversationId; + } + /** The endpoint a generation this chat did not start runs on, as the host selects it. */ private resumeEndpoint(): string | undefined { return this.init.resumeSelection?.().endpoint ?? undefined; @@ -1341,6 +1604,21 @@ export class Chat { } } + private assertNotResuming(action: Agents.PendingAction): void { + if (this.disposed) { + throw new Error('The chat was disposed'); + } + if (this.resuming === action.actionId) { + throw new Error('This pause is already being resumed'); + } + } + + private clearAction(): void { + this.action = undefined; + this.decisions.clear(); + this.notify(); + } + /** Returns a failed chat to `ready`. AI SDK: `clearError`. */ clearError(): void { if (this.status !== 'error') { @@ -1350,6 +1628,130 @@ export class Chat { this.setStatus('ready'); } + /** + * Restores a pause the server reported outside a stream, such as the status check of a reload, + * so its tool decisions and answers can be submitted. Refused while a request is in flight. + */ + restorePendingAction(action: Agents.PendingAction, generationCreatedAt: number): void { + if (this.disposed) { + return; + } + if (this.active) { + throw new Error('A request is in flight; its stream reports the pause'); + } + if (this.resumed.has(action.actionId) && generationCreatedAt === this.generationCreatedAt) { + /** A status read before the answer landed reports a pause this chat already resumed. */ + return; + } + if (this.isStaleRead(generationCreatedAt)) { + return; + } + this.newestRead = generationCreatedAt; + const dropped = this.detached?.target.generationCreatedAt; + if (this.detached && (dropped == null || generationCreatedAt > dropped)) { + /** + * The pause belongs to a newer generation, or one the dropped stream never dated, which + * superseded the one whose stream dropped. + */ + this.detached = undefined; + } + /** + * A lost start is left as it is: no read can tell whether it names that start's generation or + * an older one, so only an answer about the start itself clears it. + */ + this.learnConversation(action.conversationId); + if (this.action?.actionId !== action.actionId) { + this.decisions.clear(); + } + this.action = action; + this.generationCreatedAt = generationCreatedAt; + if (this.restored?.createdAt !== generationCreatedAt) { + /** The generation whose stream dropped keeps one record, which this read adds to. */ + const dropped = + this.detached?.target.generationCreatedAt === generationCreatedAt + ? this.detached.generation + : undefined; + this.restored = { createdAt: generationCreatedAt, generation: dropped ?? {} }; + } + /** The record carries what the status read says of the generation, for a stop or reattachment. */ + const { generation } = this.restored; + generation.paused = action.actionId; + generation.conversationId = action.conversationId ?? generation.conversationId; + if (action.responseMessageId) { + generation.responseId = action.responseMessageId; + generation.responseUnknown = false; + } else if (generation.responseId === undefined) { + generation.responseUnknown = true; + } + this.notify(); + } + + /** + * Records a decision for one paused tool call and shows it on the call. Once every call of the + * pause has one, the batch resumes the generation, which continues on the attached stream. + * AI SDK: `addToolApprovalResponse`. + */ + async addToolApprovalResponse(response: ToolApprovalResponse): Promise { + const action = this.action; + if (action?.payload.type !== 'tool_approval') { + throw new Error('No tool approval is pending'); + } + const ids = action.payload.action_requests.map((request) => request.tool_call_id); + if (!ids.includes(response.id)) { + throw new Error(`Tool call ${response.id} is not awaiting approval`); + } + this.assertNotResuming(action); + const { + id, + approved, + decision: chosen, + reason, + editedArguments, + responseText, + scope, + } = response; + const decision: Agents.ToolApprovalResolution = { + tool_call_id: id, + decision: chosen ?? (approved ? 'approve' : 'reject'), + ...(reason !== undefined && { reason }), + ...(editedArguments !== undefined && { editedArguments }), + ...(responseText !== undefined && { responseText }), + ...(scope !== undefined && { scope }), + }; + this.decisions.set(response.id, decision); + await this.executor.run(() => { + const next = markApproval(this.messages, action.actionId, response.id, decision); + if (next) { + this.write(next); + } + }); + if (ids.some((id) => !this.decisions.has(id))) { + return; + } + const decisions = ids.map((id) => this.decisions.get(id) as Agents.ToolApprovalResolution); + await this.resume(action, { decisions }); + } + + /** + * Answers an `ask_user_question` pause, which resumes the generation. AI SDK: `addToolOutput`. + * `toolCallId` is the asking tool call, or the pause's action id when the server named no call. + */ + async addToolOutput({ toolCallId, output }: ToolOutput): Promise { + const action = this.action; + if (action?.payload.type !== 'ask_user_question') { + throw new Error('No question is pending'); + } + const expected = action.payload.tool_call_id ?? action.actionId; + if (toolCallId !== expected) { + throw new Error(`Tool call ${toolCallId} is not awaiting an answer`); + } + this.assertNotResuming(action); + await this.resume( + action, + typeof output === 'string' ? { answer: output } : { answers: output }, + ); + } + /** Notifies `listener` after every change to the messages, status or error. */ subscribe(listener: () => void): () => void { this.listeners.add(listener); @@ -1415,6 +1817,9 @@ export class Chat { if (this.active) { throw new Error('A turn is already in flight for this chat'); } + if (this.action) { + throw new Error('A paused generation is waiting for a decision; answer or stop it first'); + } const active = createActiveRequest({ responseless: true }); this.active = active; try { @@ -1506,8 +1911,9 @@ export class Chat { } if (answered == null || answered !== dropped?.target.generationCreatedAt) { /** - * A start the server attached to the dropped generation continues it; any other supersedes - * it, which stays in the stale-read history so a late read of it changes nothing. + * A start the server attached to the dropped generation continues it, answered pauses + * included; any other supersedes it, and the old generation's resumed pauses with it. A + * superseded one stays in the stale-read history so a late read of it changes nothing. */ for (const superseded of [this.generationCreatedAt, dropped?.target.generationCreatedAt]) { if (superseded != null) { @@ -1515,6 +1921,7 @@ export class Chat { } } this.generationCreatedAt = undefined; + this.resumed.clear(); } let stream: ChatStream | null = null; if (result.status === 'stream') { @@ -1636,7 +2043,12 @@ export class Chat { active.generation = { endpoint, conversationId, responseUnknown: true }; } if (stream.generationCreatedAt != null) { + const previous = this.generationCreatedAt; this.generationCreatedAt = stream.generationCreatedAt; + if (this.action && previous != null && previous !== stream.generationCreatedAt) { + /** A restored pause belongs to the generation it was restored with, not this one. */ + this.clearAction(); + } } let outcome: Outcome | undefined; /** The event this chat is applying, whose failure is the chat's, not the generation's. */ @@ -1651,7 +2063,7 @@ export class Chat { 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)); + this.track(active, event); outcome = this.apply(event, active); handling = undefined; } @@ -1697,18 +2109,30 @@ export class Chat { /** Applies one event; returns the turn's outcome when the event ends it. */ private apply(event: ChatEvent, active: ActiveRequest): Outcome | undefined { - const applyEvent = this.init.applyEvent ?? defaultApplyEvent; - applyEvent(event, { - messages: this.messages, - write: (messages) => this.write(messages), - }); + /** A pause this chat already resumed is stale, so no card is drawn for it. */ + const stale = event.type === 'pending_action' && this.isStalePause(event.data); + const folded = stale ? undefined : this.withoutStalePause(event); + const disconnect = + event.type === 'error' && + (event.status === 0 || (active.attached === true && isAttachFailure(event))); + /** + * The pause is reconciled before the host reducer folds the event in, so a subscriber its + * writes notify never answers a pause the same event ended or replaced. + */ + this.reconcilePause(event, stale, disconnect); + if (folded && !this.disposed) { + const applyEvent = this.init.applyEvent ?? defaultApplyEvent; + applyEvent(folded, { + messages: this.messages, + write: (messages) => this.write(messages), + }); + } /** A listener told of that write may have disposed the chat, which then owns no more state. */ if (this.disposed) { return undefined; } let outcome: Outcome | undefined; - if (streamingEvents.has(event.type) || event.type === 'pending_action') { - /** A live pause is the generation running, however its first frame arrives. */ + if (streamingEvents.has(event.type)) { if (this.markStreaming()) { this.notify(); } @@ -1716,12 +2140,19 @@ export class Chat { if (this.disposed) { return undefined; } + } else if (event.type === 'pending_action' && !stale) { + /** A live pause is the generation running, however its first frame arrives. */ + this.markStreaming(); + this.notify(); + /** A listener told of that status may have disposed the chat too. */ + if (this.disposed) { + return undefined; + } } else if (event.type === 'final') { outcome = getFinalOutcome(event.data); } else if (event.type === 'abort') { outcome = { kind: 'abort' }; } else if (event.type === 'error') { - const disconnect = event.status === 0 || (active.attached === true && isAttachFailure(event)); const message = getErrorMessage(event.data) ?? 'The response failed'; outcome = { kind: 'error', error: new Error(message), disconnect }; } @@ -1729,6 +2160,23 @@ export class Chat { return outcome; } + /** What one event changes in the pause the chat holds and the decisions made for it. */ + private reconcilePause(event: ChatEvent, stale: boolean, disconnect: boolean): void { + if (event.type === 'pending_action' && !stale) { + if (this.action?.actionId !== event.data.actionId) { + /** A reconnect replays the same pause; decisions already made for it still stand. */ + this.decisions.clear(); + } + this.action = event.data; + } else if (event.type === 'final') { + this.action = undefined; + } else if (event.type === 'abort' || (event.type === 'error' && !disconnect)) { + /** A dropped connection leaves the server's generation, and its pause, as it was. */ + this.action = undefined; + this.decisions.clear(); + } + } + /** * Moves to `streaming` on a frame of a live generation, which also ends whatever failure a * dropped connection reported. Returns whether anything changed. @@ -1809,6 +2257,12 @@ export class Chat { */ this.active = undefined; if (outcome.kind !== 'error' || !outcome.disconnect) { + /** + * An ended generation ends its pause too, before the host hears of it, so a completion + * callback can start the next turn; only a dropped connection leaves it running. + */ + this.action = undefined; + this.decisions.clear(); /** Including an attachment that found its generation already finished. */ const ended = active.stream?.generationCreatedAt ?? @@ -1831,6 +2285,23 @@ export class Chat { ); } + /** Records the ids and pause an event reports for the request it arrived on. */ + private track(active: ActiveRequest, event: ChatEvent): void { + const identity = getFrameIdentity(event); + if (event.type === 'pending_action' && this.isStalePause(event.data)) { + /** A stale pause names neither the held pause nor the response its generation reports. */ + this.adopt(active.generation, { ...identity, responseMessageId: undefined }); + return; + } + const snapshot = event.type === 'sync' ? event.data.resumeState?.pendingAction : undefined; + if (event.type === 'pending_action') { + active.generation.paused = event.data.actionId; + } else if (snapshot && !this.isStalePause(snapshot)) { + active.generation.paused = snapshot.actionId; + } + this.adopt(active.generation, identity); + } + /** * Adopts the ids a frame names: the conversation for the generation and, for a chat started * under `new`, for the chat; and the response the generation produces, which makes it known. @@ -1850,6 +2321,7 @@ export class Chat { /** * Whether a status read names a generation this chat already knows is over or superseded: one * that ended, or one older than any generation the chat has seen, including one that since ended. + * Every consumer of a status read checks this before changing anything. */ private isStaleRead(generationCreatedAt: number): boolean { if (this.endedGenerations.has(generationCreatedAt)) { @@ -1860,10 +2332,32 @@ export class Chat { ...this.endedGenerations, this.detached?.target.generationCreatedAt, this.generationCreatedAt, + this.newestRead, ]; return seen.some((known) => known != null && generationCreatedAt < known); } + /** + * The event the host reducer folds in: a sync snapshot drops a pause this chat already resumed, + * as a standalone `pending_action` frame of it would be skipped, so no card is drawn for it. + */ + private withoutStalePause(event: ChatEvent): ChatEvent { + const snapshot = event.type === 'sync' ? event.data.resumeState?.pendingAction : undefined; + if (event.type !== 'sync' || !snapshot) { + return event; + } + if (!this.isStalePause(snapshot)) { + return event; + } + const resumeState = { ...event.data.resumeState, pendingAction: undefined }; + return { ...event, data: { ...event.data, resumeState } } as ChatEvent; + } + + /** Whether `action` was already resumed by this chat, so a replay of it is stale. */ + private isStalePause(action: Agents.PendingAction): boolean { + return this.resumed.has(action.actionId); + } + /** Adopts the conversation the server created for a chat started under `new`; a real id stays. */ private learnConversation(conversationId: string | null | undefined): void { if ( @@ -1943,6 +2437,149 @@ export class Chat { active.finish(); } + private async resume( + action: Agents.PendingAction, + resolution: + | { decisions: Agents.ToolApprovalResolution[] } + | { answer?: string; answers?: Record }, + ): Promise { + const { resume } = this.init.transport; + if (!resume) { + throw new Error('The transport cannot resume a paused generation'); + } + /** Unknown on a stream that names no generation; the server then fences by the action alone. */ + const generationCreatedAt = this.generationCreatedAt; + if (this.disposed) { + throw new Error('The chat was disposed'); + } + if (this.action?.actionId !== action.actionId) { + throw new Error('The pause ended before it was resumed'); + } + if (this.resuming === action.actionId) { + return; + } + this.resuming = action.actionId; + /** Read once: the answer and the reattachment that follows it run on the same selection. */ + let selection: ReturnType> | undefined; + try { + selection = this.init.resumeSelection?.(); + if (this.disposed) { + /** The host's selection disposed the chat, which then sends no answer for it. */ + throw new Error('The chat was disposed'); + } + /** Disposal releases the submit; a late answer then finds nothing to change. */ + const result = await untilAborted( + resume.call(this.init.transport, { + ...selection, + ...resolution, + conversationId: + action.conversationId ?? this.pausedConversationId() ?? this.conversationId, + ...(generationCreatedAt != null && { generationCreatedAt }), + actionId: action.actionId, + }), + this.lifetime.signal, + ); + this.resumed.add(action.actionId); + /** The answer names the conversation, which a chat started under `new` adopts either way. */ + this.learnConversation(result.conversationId); + /** A pause stopped or replaced while the request was in flight is no longer this one's. */ + if (this.action?.actionId !== action.actionId) { + return; + } + const reattach = this.active && !this.active.stream ? this.active.reattach : undefined; + if (reattach && this.generationCreatedAt === generationCreatedAt) { + /** A reconnect already opening attaches to the continuation, or finds it finished. */ + reattach.continuation = true; + } else if (!this.active && !this.disposed) { + /** A pause restored after a reload has no stream attached for the continuation. */ + this.reattach( + { + streamId: result.streamId, + generationCreatedAt, + conversationId: result.conversationId, + endpoint: selection?.endpoint ?? undefined, + }, + true, + ).catch((error: unknown) => + this.callHost( + this.init.onError, + error instanceof Error ? error : new Error(String(error)), + ), + ); + } + this.clearAction(); + } catch (error) { + const failure = error as ChatTransportError; + if (isPauseOver(failure)) { + /** Over for good: a later status read, replay or snapshot of it is stale, as an answered one is. */ + this.resumed.add(action.actionId); + /** + * The server answered that this pause can no longer be resumed: another client answered + * it or a newer generation replaced it. It ends here, and a probe finds what runs now. + */ + /** A newer pause restored meanwhile owns the chat, and the probe would end it. */ + const ours = this.action?.actionId === action.actionId; + const probing = (ours || !this.action) && !this.active && !this.disposed; + if (!probing && ours) { + this.clearAction(); + } + if (probing) { + /** + * Started while the pause still names its generation, so a subscriber cannot take the + * chat first; the reattachment retires the refused pause once it owns the chat, and then + * settles or replaces it by what it finds. + */ + this.reattach( + { + streamId: action.streamId, + endpoint: selection?.endpoint ?? undefined, + conversationId: action.conversationId ?? this.pausedConversationId(), + retire: action.actionId, + }, + false, + ).catch((probe: unknown) => + this.callHost( + this.init.onError, + probe instanceof Error ? probe : new Error(String(probe)), + ), + ); + } + throw error; + } + const ambiguous = isRetryableNetworkError(failure); + if ( + ambiguous && + !this.active && + !this.disposed && + this.action?.actionId === action.actionId + ) { + /** + * The answer may have reached the server, which then runs the generation again. It stays + * addressable through a reattachment, which finds the continuation, the pause or the end. + */ + this.reattach( + { + streamId: action.streamId, + endpoint: selection?.endpoint ?? undefined, + generationCreatedAt, + conversationId: action.conversationId ?? this.pausedConversationId(), + }, + true, + ).catch((failure: unknown) => + this.callHost( + this.init.onError, + failure instanceof Error ? failure : new Error(String(failure)), + ), + ); + } + throw error; + } finally { + if (this.resuming === action.actionId) { + this.resuming = undefined; + } + } + } + /** * Every write below is the chat's own; a disposed chat owns none of the shared state. `commit` * reads the list the state committed before anyone is told of it, including a store that diff --git a/packages/chat/src/core/types.ts b/packages/chat/src/core/types.ts index fd5805f894..0a45d8801a 100644 --- a/packages/chat/src/core/types.ts +++ b/packages/chat/src/core/types.ts @@ -223,8 +223,8 @@ export type ChatStreamStatus = { /** The agent selection a paused generation resumes with, matching its original request. */ export type ChatResumeSelection = { conversationId: string; - /** The paused generation being resumed. */ - generationCreatedAt: number; + /** The paused generation being resumed, when its stream named one; the action id fences it either way. */ + generationCreatedAt?: number; endpoint?: string | null; endpointType?: string | null; agent_id?: string | null;