Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

⏸️ feat: Answer, Restore and Stop a Paused Generation From the Chat Core (#17587)

Marco Berettad4374f02deef
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<never>(() => 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,118 +2121,908 @@ describe('Chat', () => {
expect(onError).not.toHaveBeenCalled();
});
- describe('stop answers and reattachment targets', () => {
- const steer = { steerId: 'steer-1', text: 'Shorter' };
+ 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'] },
+ },
+ });
- it('hands back the steers a stop found uninjected, under the conversation it stopped', async () => {
- const { chat, stream, transport } = setup();
- transport.abort.mockImplementation(async () => {
- stream.push(finalEvent({ terminalStatus: 'aborted' }));
- return { success: true, aborted: 'stream-7', pendingSteers: [steer] };
+ const 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<ChatInit> = {}) => {
+ 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 = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ 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 };
+ };
- /** The answer names the stopped stream; the conversation is the one the chat knows. */
- await expect(chat.stop()).resolves.toEqual({
- status: 'stopped',
- conversationId: 'convo-1',
- pendingSteers: [steer],
+ 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('hands back no steers from a stop the run had already settled or could not save', async () => {
- for (const answer of [
- { settled: true, terminalStatus: 'complete' as const },
- { persistenceFailed: true },
- ]) {
- const { chat, stream, transport } = setup();
- transport.abort.mockImplementation(async () => {
- stream.push(finalEvent({ terminalStatus: 'aborted' }));
- return { success: true, aborted: 'convo-1', pendingSteers: [steer], ...answer };
- });
- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
- await flush();
+ 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 expect(chat.stop()).resolves.toEqual({
- status: 'stopped',
- conversationId: 'convo-1',
- });
- await sent;
- }
+ 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('reports a turn under `new` it saw no frame for as unaddressable, leaving it attached', async () => {
- const stream = createStream();
- const { chat, transport } = setup(
- {
- id: 'new',
- prepareRequest: jest.fn(() => ({
- payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,
- messages: [userMessage, placeholder],
- responseMessageId: 'response-1',
- })),
- },
- { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },
- );
- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
- await flush();
- stream.push(stepEvent);
+ 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 expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });
+ await chat.addToolApprovalResponse({ id: 'call-2', approved: false });
- expect(transport.abort).not.toHaveBeenCalled();
- expect(chat.status).toBe('streaming');
+ 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('reports a start cancelled before it reached the transport as stopped', async () => {
- const { chat, transport } = setup({
- prepareRequest: jest.fn(() => new Promise<never>(() => undefined)),
+ 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);
+ }
});
- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+
+ 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<void> | 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.stop()).resolves.toEqual({ status: 'stopped' });
- await sent.catch(() => undefined);
- expect(transport.sendMessages).not.toHaveBeenCalled();
+ 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('sends no stop for a late start it cannot name', async () => {
- let open: ((result: { status: 'stream'; stream: ChatStream }) => void) | undefined;
- const late = createStream();
- const { chat, transport, onError } = setup(
- {
- id: 'new',
- prepareRequest: jest.fn(() => ({
- payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,
- messages: [userMessage, placeholder],
- responseMessageId: 'response-1',
- })),
- },
+ 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' }) },
{
- sendMessages: jest.fn(
+ resume: jest.fn(
() =>
- new Promise<{ status: 'stream'; stream: ChatStream }>((resolve) => {
- open = resolve;
+ new Promise((resolve) => {
+ accept = () =>
+ resolve({ streamId: 'convo-1', conversationId: 'convo-1', status: 'resuming' });
}),
),
},
);
- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ 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);
- await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });
- open?.({ status: 'stream', stream: late });
- await sent.catch(() => undefined);
+ accept?.();
+ await answered;
await flush();
- expect(late.closed()).toBe(true);
- expect(transport.abort).not.toHaveBeenCalled();
- expect(onError).toHaveBeenCalledTimes(1);
+ 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<null>(() => 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<Transport>).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();
+ transport.abort.mockImplementation(async () => {
+ stream.push(finalEvent({ terminalStatus: 'aborted' }));
+ return { success: true, aborted: 'stream-7', pendingSteers: [steer] };
+ });
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ await flush();
+
+ /** The answer names the stopped stream; the conversation is the one the chat knows. */
+ await expect(chat.stop()).resolves.toEqual({
+ status: 'stopped',
+ conversationId: 'convo-1',
+ pendingSteers: [steer],
+ });
+ await sent;
+ });
+
+ it('hands back no steers from a stop the run had already settled or could not save', async () => {
+ for (const answer of [
+ { settled: true, terminalStatus: 'complete' as const },
+ { persistenceFailed: true },
+ ]) {
+ const { chat, stream, transport } = setup();
+ transport.abort.mockImplementation(async () => {
+ stream.push(finalEvent({ terminalStatus: 'aborted' }));
+ return { success: true, aborted: 'convo-1', pendingSteers: [steer], ...answer };
+ });
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ await flush();
+
+ await expect(chat.stop()).resolves.toEqual({
+ status: 'stopped',
+ conversationId: 'convo-1',
+ });
+ await sent;
+ }
+ });
+
+ it('reports a turn under `new` it saw no frame for as unaddressable, leaving it attached', async () => {
+ const stream = createStream();
+ const { chat, transport } = setup(
+ {
+ id: 'new',
+ prepareRequest: jest.fn(() => ({
+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,
+ messages: [userMessage, placeholder],
+ responseMessageId: 'response-1',
+ })),
+ },
+ { sendMessages: jest.fn(async () => ({ status: 'stream' as const, stream })) },
+ );
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ await flush();
+ stream.push(stepEvent);
+ await flush();
+
+ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });
+
+ expect(transport.abort).not.toHaveBeenCalled();
+ expect(chat.status).toBe('streaming');
+ stream.push(finalEvent());
+ await sent;
+ });
+
+ it('reports a start cancelled before it reached the transport as stopped', async () => {
+ const { chat, transport } = setup({
+ prepareRequest: jest.fn(() => new Promise<never>(() => undefined)),
+ });
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ await flush();
+
+ await expect(chat.stop()).resolves.toEqual({ status: 'stopped' });
+ await sent.catch(() => undefined);
+ expect(transport.sendMessages).not.toHaveBeenCalled();
+ });
+
+ it('sends no stop for a late start it cannot name', async () => {
+ let open: ((result: { status: 'stream'; stream: ChatStream }) => void) | undefined;
+ const late = createStream();
+ const { chat, transport, onError } = setup(
+ {
+ id: 'new',
+ prepareRequest: jest.fn(() => ({
+ payload: { endpoint: 'assistants', text: 'Hi' } as TPayload,
+ messages: [userMessage, placeholder],
+ responseMessageId: 'response-1',
+ })),
+ },
+ {
+ sendMessages: jest.fn(
+ () =>
+ new Promise<{ status: 'stream'; stream: ChatStream }>((resolve) => {
+ open = resolve;
+ }),
+ ),
+ },
+ );
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] });
+ await flush();
+
+ await expect(chat.stop()).resolves.toEqual({ status: 'unaddressable' });
+ open?.({ status: 'stream', stream: late });
+ await sent.catch(() => undefined);
+ await flush();
+
+ expect(late.closed()).toBe(true);
+ expect(transport.abort).not.toHaveBeenCalled();
+ expect(onError).toHaveBeenCalledTimes(1);
});
it("stops an Assistants run by the ids its sync frame named, from that frame's own callback", async () => {
@@ -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' }] });
@@ -2519,40 +3463,356 @@ describe('Chat', () => {
stream.push({ type: 'error', status: 0, data: 'offline' } as ChatEvent);
await sent;
transport.reconnectToStream.mockResolvedValueOnce(reattached);
- const resumed = chat.resumeStream({ streamId: 'convo-1' });
+ const resumed = chat.resumeStream({ streamId: 'convo-1' });
+ await flush();
+
+ reattached.push({ type: 'abort', data: {} } as ChatEvent);
+ await resumed;
+
+ expect(onFinish).toHaveBeenLastCalledWith(
+ expect.objectContaining({ isAbort: true, isResponseUnknown: true, message: undefined }),
+ );
+ });
+
+ 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<ChatStream | null>((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<void>[] = [];
+ 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(
+ {},
+ {
+ sendMessages: jest.fn(async () => ({
+ status: 'replaced' as const,
+ generationProtocolVersion: 2,
+ conversationId: 'convo-1',
+ streamId: 'stream-2',
+ generationCreatedAt: 200,
+ })),
+ reconnectToStream: jest.fn(async () => stream),
+ },
+ );
+ const options = { headers: { 'x-tenant': 'acme' }, body: { spec: 'a' } };
+ const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }, options);
+ await flush();
+ stream.push(finalEvent());
+ await sent;
+
+ expect(transport.reconnectToStream).toHaveBeenCalledWith(
+ expect.objectContaining({ ...options, chatId: 'convo-1', streamId: 'stream-2' }),
+ );
+ });
+
+ 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<ChatAbortResult>((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<ChatAbortResult>((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');
- reattached.push({ type: 'abort', data: {} } as ChatEvent);
+ 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, isResponseUnknown: true, message: undefined }),
+ expect.objectContaining({ isAbort: true, isDisconnect: false }),
);
});
- it('sends the request options of a turn to the generation that replaced it', async () => {
- const stream = createStream();
- const { chat, transport } = setup(
- {},
- {
- sendMessages: jest.fn(async () => ({
- status: 'replaced' as const,
- generationProtocolVersion: 2,
- conversationId: 'convo-1',
- streamId: 'stream-2',
- generationCreatedAt: 200,
- })),
- reconnectToStream: jest.fn(async () => stream),
- },
+ 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<ChatAbortResult>((resolve) => {
+ answer = resolve;
+ }),
);
- const options = { headers: { 'x-tenant': 'acme' }, body: { spec: 'a' } };
- const sent = chat.sendMessage({ parts: [{ type: 'text', text: 'Hi' }] }, options);
+ 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();
- stream.push(finalEvent());
- await sent;
- expect(transport.reconnectToStream).toHaveBeenCalledWith(
- expect.objectContaining({ ...options, chatId: 'convo-1', streamId: 'stream-2' }),
+ 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<unknown>[] = [];
+ 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 }),
);
});
@@ -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<Extract<ChatEvent, { type: 'final' }>['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<string, (h: Harness) => Promise<void>> = {
);
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<string, (h: Harness) => Promise<void>> = {
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<string, (h: Harness) => Promise<void>> = {
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<string, (h: Harness) => Promise<unknown>> = {
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,13 +1756,39 @@ describe('Chat final frames', () => {
});
});
-const createdUnder = 'convo-9';
-const learns: Array<[string, (h: Harness) => Promise<void>]> = [
- [
- 'a sync frame',
- async (h) => {
- const stream = createStream({ streamId: createdUnder, generationCreatedAt: 100 });
- attach(h, stream);
+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<void>]> = [
+ [
+ 'a sync frame',
+ async (h) => {
+ const stream = createStream({ streamId: createdUnder, generationCreatedAt: 100 });
+ attach(h, stream);
send(h);
await flush();
stream.push({
@@ -1384,6 +1826,14 @@ const learns: Array<[string, (h: Harness) => Promise<void>]> = [
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<void>, 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<void>, 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<void> | 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<ChatResumeSelection, 'conversationId' | 'generationCreatedAt'>;
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<string, string>;
+};
+
/** 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<number>();
+ /** The generation a restored pause belongs to, which a reattachment to it continues. */
+ private restored?: { createdAt: number; generation: Generation };
+ private readonly decisions = new Map<string, Agents.ToolApprovalResolution>();
+ /** Pauses already resumed, or refused as over, whose replay or later status read is stale. */
+ private readonly resumed = new Set<string>();
+ /** 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<void> {
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<void> {
+ 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<void> {
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<ChatStopResult> {
+ 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<void> {
+ 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<void> {
+ 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<string, string> },
+ ): Promise<void> {
+ 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<NonNullable<ChatInit['resumeSelection']>> | 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;