From 82c4b4f5a89a606e5e65c9cf090f531d8959d9ad Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 17 Nov 2026 17:01:05 -0800 Subject: [PATCH] feat(ag-ui): regenerate a response from the React AG-UI session Core AgentSession has an optional regenerate(messageId), and React Chat offers Regenerate whenever a session supplies it. The LangGraph runtime does; the AG-UI runtime did not, so AG-UI chats had no Regenerate action even though the Angular AG-UI adapter supports it. The plain native owner now has regenerate(messageId, options?) with the Angular adapter's semantics: it finds the root assistant record (or the reasoning record a reasoning-only answer is shown under), keeps history through the user message before it, drops everything after, and sends a run with that history and the current state without adding the prompt again. It rejects without sending after disposal, during a run, while a decision waits, for an id that is not an assistant record, and when no prompt precedes it, matching the core contract. A failed regenerate can be retried from the same trimmed history. createAgentSession forwards it as the core regenerate. The client-tool owner is left without it because its ledger owns the call history, as it is for retry. Co-Authored-By: Claude Opus 5.5 --- .../ag-ui-candidate/installed-types.ts | 6 + libs/ag-ui/src/runtime/README.md | 25 +- libs/ag-ui/src/runtime/agent-session.ts | 25 +- libs/ag-ui/src/runtime/create-session.ts | 70 ++++++ libs/ag-ui/src/runtime/regenerate.spec.ts | 235 ++++++++++++++++++ 5 files changed, 354 insertions(+), 7 deletions(-) create mode 100644 libs/ag-ui/src/runtime/regenerate.spec.ts diff --git a/fixtures/react-parity/ag-ui-candidate/installed-types.ts b/fixtures/react-parity/ag-ui-candidate/installed-types.ts index ec917feab..41b3c86bb 100644 --- a/fixtures/react-parity/ag-ui-candidate/installed-types.ts +++ b/fixtures/react-parity/ag-ui-candidate/installed-types.ts @@ -107,6 +107,12 @@ export function checkCandidate(signal: AbortSignal) { void agent.submit({ message: 'Hello' }); // @ts-expect-error Native resume stays on the native session. void agent.resume; + const regenerated: Promise | undefined = + session.regenerate?.('assistant-id', { signal }); + void regenerated; + void agent.regenerate?.('assistant-id', { signal }); + // @ts-expect-error Regenerate takes a message id, not an index. + void session.regenerate?.(1); // @ts-expect-error The view wraps a session, not its options. createAgentSession(options); return { session, snapshot, rows, stable, messages, toolCalls, agent, core }; diff --git a/libs/ag-ui/src/runtime/README.md b/libs/ag-ui/src/runtime/README.md index 76427d3e6..68971079d 100644 --- a/libs/ag-ui/src/runtime/README.md +++ b/libs/ag-ui/src/runtime/README.md @@ -146,8 +146,9 @@ const session = createAgentSession(native); changes. Subscribers hear about those changes only, so a native publication that touches only state, child evidence or a decision is silent here. - `submit` takes text and goes straight to the native session, as do `stop` and - `dispose`. Disposing the view disposes the session. `retry` goes to the native - session too, when it has one (see "Retry" below). + `dispose`. Disposing the view disposes the session. `retry` and `regenerate` + go to the native session too, when it has them (see "Retry" and + "Regenerate" below). - A failed run becomes `snapshot.error`. A backend `RUN_ERROR` is a `server` error carrying the backend's message. A stream that ended without a terminal is `interrupted`. A response that was not OK carries its HTTP status: 401 and @@ -195,6 +196,26 @@ otherwise resolves with the native re-run's outcome. - A `RUN_ERROR` settles that the run failed, not that it did nothing. Work the backend did before failing can be repeated. +### Regenerate + +The plain native owner has `regenerate(messageId, options?)`, with the same +semantics as the Angular adapter's `regenerate`. It takes the `id` of a root +assistant record, or of the reasoning record a reasoning-only answer is shown +under, which is the `id` the core view gives that message. It keeps the history +up to and including the user message before that record, drops everything after +it, and sends a run with that history and the current state. The prompt is not +added again. Regenerating an earlier answer drops every later turn. + +- It rejects without sending after disposal, while a run is active, while a + decision is waiting, for an id that is not an assistant record, and when no + user message precedes it. +- A regenerate that fails with a backend `RUN_ERROR` can be sent again with + `retry`, from the same trimmed history. +- The core view forwards it as the core session's `regenerate`, so React `Chat` + offers Regenerate on assistant messages. +- The client-tool owner has no `regenerate`: its ledger owns the history of the + calls it ran, and trimming that history is not supported. + ### Approvals `decisionState(snapshot)` reads the native snapshot's pending decision and how diff --git a/libs/ag-ui/src/runtime/agent-session.ts b/libs/ag-ui/src/runtime/agent-session.ts index b06c0d3c8..8f07e395c 100644 --- a/libs/ag-ui/src/runtime/agent-session.ts +++ b/libs/ag-ui/src/runtime/agent-session.ts @@ -3,6 +3,7 @@ import type { AgentSession, AgentSessionCustomEvent, AgentSnapshot, + AgentSubmitOptions, AgentUsage, AgentUsageEntry, } from '@threadplane/core'; @@ -16,7 +17,13 @@ import { /** The native owner, with or without a client-tool catalog. */ export type NativeSession = Pick< Session, - 'subscribe' | 'submit' | 'stop' | 'dispose' | 'retry' | 'onCustomEvent' + | 'subscribe' + | 'submit' + | 'stop' + | 'dispose' + | 'retry' + | 'regenerate' + | 'onCustomEvent' > & { getSnapshot(): SessionSnapshot }; /** @@ -165,10 +172,11 @@ function project( * It is a view, not a second owner. The snapshot is derived from the native * snapshot on read and keeps its reference until something a core observer can * see changes; subscribers are told about those changes only. `submit`, `stop`, - * `dispose` and, when the native session has it, `retry` go straight to the - * native session, so disposing the view disposes the session. `retry` rejects - * unless the error is `recovery: 'retry'`. Custom event listeners pass straight - * through to the native session too, when it has them. Application state, + * `dispose` and, when the native session has them, `retry` and `regenerate` + * go straight to the native session, so disposing the view disposes the + * session. `retry` rejects unless the error is `recovery: 'retry'`. Custom + * event listeners pass straight through to the native session too, when it + * has them. Application state, * native resume and client-tool evidence have no core equivalent: keep the * native session for those. */ @@ -176,6 +184,7 @@ export function createAgentSession(session: NativeSession): AgentSession { let seen: SessionSnapshot | undefined; let current: AgentSnapshot | undefined; const retry = session.retry; + const regenerate = session.regenerate; const listen = session.onCustomEvent; const getSnapshot = (): AgentSnapshot => { const native = session.getSnapshot(); @@ -204,6 +213,12 @@ export function createAgentSession(session: NativeSession): AgentSession { submit: (input, options) => session.submit(input, options), stop: () => session.stop(), dispose: () => session.dispose(), + // The native owner rejects what it cannot regenerate, as the core + // contract asks, so the command passes straight through. + ...(regenerate && { + regenerate: (messageId: string, options?: AgentSubmitOptions) => + regenerate.call(session, messageId, options), + }), ...(retry && { async retry() { const snapshot = getSnapshot(); diff --git a/libs/ag-ui/src/runtime/create-session.ts b/libs/ag-ui/src/runtime/create-session.ts index 06e20f36d..51e33c7a7 100644 --- a/libs/ag-ui/src/runtime/create-session.ts +++ b/libs/ag-ui/src/runtime/create-session.ts @@ -100,6 +100,21 @@ export interface Session { * owner, which blocks every dispatched failure as uncertain. */ retry?(): Promise; + /** + * Answers the prompt behind one assistant message again, as the Angular + * adapter's `regenerate` does. Takes the `id` of a root assistant record (or + * of the reasoning record a reasoning-only answer is shown under), drops + * every record after the user message that precedes it, and sends a run + * with that history and the current state. The prompt is not added again. + * Rejects without sending while a run is active, while a decision is + * waiting, after disposal, for an id that is not an assistant record, and + * when no user message precedes it. `retry` can send a failed regenerate + * again. Absent on the client-tool owner, whose ledger owns its history. + */ + regenerate?( + messageId: string, + options?: { readonly signal?: AbortSignal } + ): Promise; /** * Listens for `CUSTOM` events other than `on_interrupt` while runs stream. * The factory always supplies it; it is optional so hand-written sessions @@ -619,6 +634,61 @@ export function createSession( ); }); }), + regenerate: (messageId, options) => + new Promise((resolve, reject) => { + const signal = options?.signal; + publication.command(() => { + const previous = publication.getSnapshot(); + let prompt = -1; + try { + if (disposed) throw new Error('The session is disposed.'); + if (active) + throw new Error('Cannot regenerate while a response is running.'); + if (previous.decision) + throw new Error('Cannot regenerate while a decision is waiting.'); + const { transcript } = previous; + const root = (index: number) => + typeof transcript[index].subagentRunId !== 'string'; + const at = transcript.findIndex( + (record, index) => + record.id === messageId && + (record.role === 'assistant' || record.role === 'reasoning') && + root(index) + ); + if (at < 0) + throw new Error('Regenerate needs the id of an assistant message.'); + for (let index = at - 1; index >= 0 && prompt < 0; index--) + if (transcript[index].role === 'user' && root(index)) + prompt = index; + if (prompt < 0) throw new Error('No prompt precedes that message.'); + } catch (error) { + reject(error); + return; + } + if (signal?.aborted) { + resolve('aborted'); + return; + } + const id = crypto.randomUUID(); + // Keep the prompt: it ends the history and is the next run's input. + const transcript = Object.freeze( + previous.transcript.slice(0, prompt + 1) + ); + saved = { runId: id, transcript, state: previous.state }; + admit( + id, + Object.freeze({ + ...previous, + status: 'running', + transcript, + ...nextInvocationSubagents(previous), + run: Object.freeze({ id }), + }), + signal, + resolve + ); + }); + }), stop: () => close(false), dispose: () => close(true), }; diff --git a/libs/ag-ui/src/runtime/regenerate.spec.ts b/libs/ag-ui/src/runtime/regenerate.spec.ts new file mode 100644 index 000000000..b5eb75c06 --- /dev/null +++ b/libs/ag-ui/src/runtime/regenerate.spec.ts @@ -0,0 +1,235 @@ +import { describe, expect, it } from 'vitest'; +import { createAgentSession } from './agent-session'; +import { createSession } from './create-session'; +import { bindingFixture } from './testing/binding-fixture'; + +type Fixture = ReturnType; +type Exchange = Awaited>; + +function answer(exchange: Exchange, messageId: string, text: string) { + exchange.emit({ type: 'TEXT_MESSAGE_START', messageId, role: 'assistant' }); + exchange.emit({ type: 'TEXT_MESSAGE_CONTENT', messageId, delta: text }); + exchange.emit({ type: 'TEXT_MESSAGE_END', messageId }); +} +function finish(exchange: Exchange) { + exchange.emit({ + type: 'RUN_FINISHED', + threadId: exchange.body.threadId, + runId: exchange.body.runId, + }); +} +/** Calls regenerate, failing the test instead of passing when the session has none. */ +function regenerateOf( + session: { regenerate?(id: string): Promise }, + id: string +): Promise { + if (!session.regenerate) throw new Error('The session has no regenerate.'); + return session.regenerate(id); +} + +/** Two settled turns: Rome then Paris. */ +async function twoTurns(fixture: Fixture) { + const session = createAgentSession(fixture.session); + const first = session.submit('Plan Rome'); + const one = await fixture.started(); + answer(one, 'rome', 'Rome plan'); + finish(one); + await expect(first).resolves.toBe('success'); + const second = session.submit('Plan Paris'); + const two = await fixture.started(1); + answer(two, 'paris', 'Paris plan'); + finish(two); + await expect(second).resolves.toBe('success'); + return { session, one, two }; +} + +describe('regenerate over the native owner', () => { + it('answers the latest prompt again and drops the earlier answer', async () => { + const fixture = bindingFixture(); + try { + const { session, two } = await twoTurns(fixture); + const regenerated = regenerateOf(session, 'paris'); + const three = await fixture.started(2); + // The request ends with the prompt; the old answer is not sent, and no + // second user message is added. + expect(three.body.messages).toEqual(two.body.messages); + expect(three.body.runId).not.toBe(two.body.runId); + const running = session.getSnapshot(); + expect(running.status).toBe('running'); + expect(running.messages.map((message) => message.content)).toEqual([ + 'Plan Rome', + 'Rome plan', + 'Plan Paris', + ]); + + answer(three, 'paris-2', 'Another Paris plan'); + finish(three); + await expect(regenerated).resolves.toBe('success'); + expect( + session.getSnapshot().messages.map((message) => message.content) + ).toEqual(['Plan Rome', 'Rome plan', 'Plan Paris', 'Another Paris plan']); + } finally { + await fixture.cleanup(); + } + }); + + it('regenerates an earlier answer by dropping every turn after its prompt', async () => { + const fixture = bindingFixture(); + try { + const { session, one } = await twoTurns(fixture); + const regenerated = regenerateOf(session, 'rome'); + const three = await fixture.started(2); + expect(three.body.messages).toEqual(one.body.messages); + expect( + session.getSnapshot().messages.map((message) => message.content) + ).toEqual(['Plan Rome']); + answer(three, 'rome-2', 'Another Rome plan'); + finish(three); + await expect(regenerated).resolves.toBe('success'); + expect( + session.getSnapshot().messages.map((message) => message.content) + ).toEqual(['Plan Rome', 'Another Rome plan']); + } finally { + await fixture.cleanup(); + } + }); + + it('regenerates an answer from a loaded thread', async () => { + const fixture = bindingFixture({ + messages: [ + { id: 'u1', role: 'user', content: 'Hello' }, + { id: 'a1', role: 'assistant', content: 'Hi' }, + ], + }); + try { + const regenerated = regenerateOf(fixture.session, 'a1'); + const exchange = await fixture.started(); + expect(exchange.body.messages).toEqual([ + { id: 'u1', role: 'user', content: 'Hello' }, + ]); + finish(exchange); + await expect(regenerated).resolves.toBe('success'); + } finally { + await fixture.cleanup(); + } + }); + + it('rejects an unknown id, a user message, and an answer with no prompt before it, sending nothing', async () => { + const fixture = bindingFixture({ + messages: [ + { id: 'greeting', role: 'assistant', content: 'Welcome' }, + { id: 'u1', role: 'user', content: 'Hello' }, + { id: 'a1', role: 'assistant', content: 'Hi' }, + ], + }); + try { + const before = fixture.session.getSnapshot(); + await expect(regenerateOf(fixture.session, 'missing')).rejects.toThrow( + 'Regenerate needs the id of an assistant message.' + ); + await expect(regenerateOf(fixture.session, 'u1')).rejects.toThrow( + 'Regenerate needs the id of an assistant message.' + ); + await expect(regenerateOf(fixture.session, 'greeting')).rejects.toThrow( + 'No prompt precedes that message.' + ); + expect(fixture.exchanges).toHaveLength(0); + expect(fixture.session.getSnapshot()).toBe(before); + } finally { + await fixture.cleanup(); + } + }); + + it('rejects while a response is running and leaves that run alone', async () => { + const fixture = bindingFixture({ + messages: [ + { id: 'u1', role: 'user', content: 'Hello' }, + { id: 'a1', role: 'assistant', content: 'Hi' }, + ], + }); + try { + const running = fixture.session.submit('Again'); + const exchange = await fixture.started(); + await expect(regenerateOf(fixture.session, 'a1')).rejects.toThrow( + 'Cannot regenerate while a response is running.' + ); + expect(fixture.exchanges).toHaveLength(1); + finish(exchange); + await expect(running).resolves.toBe('success'); + } finally { + await fixture.cleanup(); + } + }); + + it('rejects while a decision is waiting', async () => { + const fixture = bindingFixture({ + messages: [ + { id: 'u1', role: 'user', content: 'Hello' }, + { id: 'a1', role: 'assistant', content: 'Hi' }, + ], + }); + try { + const paused = fixture.session.submit('Book it'); + const exchange = await fixture.started(); + exchange.emit({ + type: 'RUN_FINISHED', + threadId: exchange.body.threadId, + runId: exchange.body.runId, + outcome: { + type: 'interrupt', + interrupts: [{ id: 'approval', reason: 'Approve' }], + }, + }); + await expect(paused).resolves.toBe('paused'); + await expect(regenerateOf(fixture.session, 'a1')).rejects.toThrow( + 'Cannot regenerate while a decision is waiting.' + ); + expect(fixture.exchanges).toHaveLength(1); + } finally { + await fixture.cleanup(); + } + }); + + it('rejects after disposal', async () => { + const fixture = bindingFixture({ + messages: [ + { id: 'u1', role: 'user', content: 'Hello' }, + { id: 'a1', role: 'assistant', content: 'Hi' }, + ], + }); + await fixture.session.dispose(); + await expect(regenerateOf(fixture.session, 'a1')).rejects.toThrow( + 'The session is disposed.' + ); + expect(fixture.exchanges).toHaveLength(0); + await fixture.cleanup(); + }); + + it('lets retry send a failed regenerate again with the trimmed history', async () => { + const fixture = bindingFixture(); + try { + const { session, one } = await twoTurns(fixture); + const regenerated = regenerateOf(session, 'rome'); + const three = await fixture.started(2); + three.emit({ type: 'RUN_ERROR', message: 'Model overloaded' }); + await expect(regenerated).resolves.toBe('error'); + expect(session.getSnapshot().error?.recovery).toBe('retry'); + const retried = session.retry?.(); + const four = await fixture.started(3); + expect(four.body.messages).toEqual(one.body.messages); + finish(four); + await expect(retried).resolves.toBe('success'); + } finally { + await fixture.cleanup(); + } + }); + + it('is absent on the client-tool owner and on its core view', () => { + const owner = createSession( + { threadId: 't', url: 'https://native-fixture.invalid/run' }, + { f: { description: 'f', handler: () => 'ok' } } + ); + expect('regenerate' in owner).toBe(false); + expect('regenerate' in createAgentSession(owner)).toBe(false); + }); +});