[ZEPPELIN-6742] Connect the AI Assistant frontend to conversation REST and WebSocket APIs by voidmatcha · Pull Request #5563 · apache/zeppelin

voidmatcha · 2026-10-09T01:29:21Z

What is this PR for?

Connect the Assistant frontend to the conversation REST and WebSocket APIs. The transport provides conversation creation and retrieval, message sending, and response delivery for the UI.

Server PR #5547, #5558, and UI contracts #5561 have merged. This PR is now based on master.

What type of PR is it?

Feature

Todos

Merge [ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side) #5547
Merge [ZEPPELIN-6738] Upgrade React to 19 and fix shared host integration #5558
Merge [ZEPPELIN-6741] Define shared AI Assistant UI contracts and message history behavior #5561 before this PR
Rebase onto master, retarget this PR to master, and rerun CI before merging
Compare against the final API contract from server PR [ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side) #5547
Confirm CI on the current PR head

What is the Jira issue?

ZEPPELIN-6742

How should this be tested?

Run from zeppelin-web-angular/:

npm run build-project:sdk
npm run typecheck:react
npm --prefix projects/zeppelin-react test -- src/entities/assistant/model/assistantTransport.spec.ts

Also verify the REST and WebSocket integration against the final API contract from server PR #5547.

Screenshots (if appropriate)

N/A

Questions:

Does the license files need to update? No
Is there breaking changes for older versions? No
Does this needs documentation? No

voidmatcha · 2026-10-09T10:05:18Z

This PR connects the frontend to the conversation REST API and WebSocket run events.

The current diff is +1,271/-8 across five files. Excluding 795 lines in *.spec.* tests, the review diff is +476/-8. There is no lockfile change.

Server PR #5547, #5558, and #5561 have merged, and this PR targets master. The latest history rewrite preserves the previous file tree. I will confirm CI on the new head before merging.

miinhho

Transport-level review. I reproduced the reported sequences by loading the module and controlling HTTP responses and socket events. I have not verified them against a live server or the notebook UI. The authentication comment is a contract question, not a confirmed integration defect.

miinhho · 2026-10-11T07:14:13Z

+// ACKs belong to the connection, even if the note or conversation that sent the request has unmounted.
+const trackPendingRun = (socket: AssistantSocket, conversationId: string, tracking: RunTracking): PendingRun => {
+  const pending: PendingRun = { abandoned: false };
+  tracking.disconnected.delete(conversationId);


This removes the previous disconnected marker before the new request has been accepted.

I reproduced this sequence: run A starts, its connection closes, and a retry is sent without reloading history. When that retry receives run.failed with status 409, the transport reports idle, even though A's history has not been recovered. The failure message itself says the conversation is still answering.

This conflicts with the documented behavior of retaining the lost-connection state until history is reloaded. Please preserve that uncertainty when the retry is rejected, and cover the disconnect → retry → 409 sequence in a regression test.

Thanks for catching this. I addressed the disconnect -> retry -> 409 sequence in 1161409d6 under the earlier run-state design. The later simplification in 42f456587 removed disconnected tracking and that regression test, so this state transition no longer exists in the current PR.

miinhho · 2026-10-11T07:14:13Z

+        {},
+        onAuthError
+      );
+      if (!before && runs.disconnected.delete(conversationId)) notifyRunState(runs, conversationId);


A successful latest-page response clears the current disconnected marker without checking whether the request predates that disconnect.

I reproduced this with an accepted run: start getMessages(), delay its response, close the socket, then release the history response. The state changes from disconnected to idle, although no history request was started after the connection loss.

Please ensure that a request spanning a newer disconnect cannot clear that disconnect's recovery state, and add a regression test for this ordering.

Thanks for catching the race. I addressed the history-response ordering in 5740ccdc2 under the earlier run-state design. The later simplification in 42f456587 removed disconnected tracking and that regression test, so this state transition no longer exists in the current PR.

seung-00 · 2026-10-16T12:18:18Z

    ...later,
-    content: [earlier.content, later.content].filter(Boolean).join('\n\n'),
-    ...(toolCalls.length ? { toolCalls } : {})
+    segments


These parts seem to conflict with the changes in #5561

Right, these overlapped with the segments changes in #5561. Now that #5561 has merged, I rebased onto master and retargeted, so those files match master and only the auth error change remains in d098067e5.

seung-00 · 2026-10-16T13:11:05Z

+  typeof value === 'object' && value !== null && 'body' in value ? value.body : value;
+
+/** Hands 401/405 to the host, which owns login redirects and logout. */
+export type AssistantAuthErrorHandler = (status: number, location: string | null) => void;


The server doesn’t provide a redirect location. I’d prefer to leave unimplemented features out of the contract. What do you think?

You're right. Nothing on the server sets Location on a 401: form auth redirects to /api/login with a 302 that fetch follows to a 405, and Kerberos returns a 401 with only WWW-Authenticate. I narrowed the handler to (status: number) => void and dropped location from the error in d098067e5.

seung-00 · 2026-10-16T16:18:38Z

+  disconnected: Map<string, object>;
+  listeners: Map<string, Set<(state: AssistantRunState) => void>>;
+  stopTracking?: () => void;
+}


I wonder if we could simplify the per-conversation state tracking a bit. One concern is that a client-side timeout leaves pending and active intact. If no terminal event arrives and the WebSocket stays connected, the conversation could remain blocked.

Some of this complexity seems to come from sharing the notebook WebSocket, where events can keep arriving after the user leaves the view. A separate assistant WebSocket tied to the component lifecycle might simplify this eventually.

One approach we could consider for this PR, without changing the server, is:

Keep a single slot for the current request:
for example: : { conversationId, phase: 'pending' | 'running', runId? }
The server already rejects concurrent requests in the same conversation with 409. We could ignore events whose conversationId does not match the slot, and clear both the slot and its subscription when the component unmounts.

Track the remaining edge case separately:
A user sends hi in conversation C1, leaves the page, then returns to C1 and sends bye. An event from hi could arrive while the client is waiting for bye and be mistaken for its response.
The single-slot approach would not fully handle this timing-dependent case, but it seems unlikely to happen often. Could we open a separate issue for it and address it later?

Thanks, done in 42f456587. Each run now keeps only its own { conversationId, phase, runId? }, drops events for other conversations, and releases its subscriptions when it ends. Duplicate sends are left to the server's 409, and the abandoned/disconnected tracking is gone. After rebasing onto master, I also dropped the now unused AssistantRunState and subscribeRunState from the contract in a5127fe31.

Could you open an issue for 2? Retrying after a client timeout and losing events after a reconnect share the same cause, so it would be good to include them too.

One additional case for the follow-up issue: if two openRun() calls for the same conversation are pending at the same time, both can accept the first run.started and bind to the same runId. The second request’s 409 run.failed may then be ignored. This seems to be another consequence of not being able to correlate a client request with its initial server response. Could we include this scenario as well?

@voidmatcha @tbonelee
Created a follow-up issue: https://issues.apache.org/jira/browse/ZEPPELIN-6753

tbonelee · 2026-10-17T13:45:14Z

+      return active && !sessionSignal?.aborted;
+    },
+    transport,
+    setActive(next: boolean) {


Could you clarify which UX scenario requires the same scopeTransport to be deactivated and later reactivated? Managing a reactivatable active flag alongside the permanent sessionSignal and per-run signals seems to add lifecycle complexity.

It also leaves an edge case where a REST request started before setActive(false) can finish after setActive(true) and still pass guarded(). If this is for panel visibility, that could perhaps be managed separately. If it is for revisiting a note, we could cache its UI state and recreate the lightweight transport instead.

If reactivation is not required, would a one-shot per-note scope with an AbortSignal for both REST and WebSocket work be simpler?

tbonelee · 2026-10-17T13:49:29Z

+  // The server names an untitled conversation by its creation time.
+  const titleFor = (title?: string) => {
+    const trimmed = title?.trim().replace(/\s+/g, ' ');
+    return trimmed ? { title: trimmed.length > 80 ? `${trimmed.slice(0, 79)}…` : trimmed } : {};


Is this normalization and 80-character limit intended to be a UI presentation rule or a conversation invariant? The server does not appear to enforce the same policy, so stored titles can differ depending on the client. If it is an invariant, could it be enforced server-side as well? If it is only presentational, truncating before persistence may discard part of the original title.

voidmatcha · 2026-10-17T14:17:56Z

@tbonelee Thanks for the careful review. I made the per-note transport scope one-shot in 23880cd1a and removed client-side title normalization and truncation in 34034fc04.

I agree that concurrent openRun() calls are another case of the request-to-run correlation problem. @seung-00, could you include that case in the follow-up issue you proposed?

… errors

…read

seung-00 · 2026-10-18T01:47:06Z

+  listConversations(signal?: AbortSignal): Promise<AssistantConversation[]>;
+  createConversation(body: { title?: string }, signal?: AbortSignal): Promise<AssistantConversation>;
+  deleteConversation(conversationId: string, signal?: AbortSignal): Promise<void>;
  /** The latest page of history, or the page before `before` (a page cursor). */
-  getMessages(conversationId: string, before?: string): Promise<AssistantMessagePage>;
-  /** Observe local run state, including a lost connection until history is reloaded. */
-  subscribeRunState?(conversationId: string, listener: (state: AssistantRunState) => void): () => void;
+  getMessages(conversationId: string, before?: string, signal?: AbortSignal): Promise<AssistantMessagePage>;


Is there a specific reason these REST calls need AbortSignal, unlike our other API calls? I understand its role in stopping the WebSocket event loop, but I’m not sure we need it for these regular REST requests as well.

seung-00 · 2026-10-18T02:00:15Z

-  subscribeRunState?(conversationId: string, listener: (state: AssistantRunState) => void): () => void;
+  getMessages(conversationId: string, before?: string, signal?: AbortSignal): Promise<AssistantMessagePage>;
  /** Aborting stops local event consumption; it does not cancel a run already accepted by the server. */
  openRun(conversationId: string, body: AssistantRunBody, signal: AbortSignal): AsyncIterable<AssistantRunEvent>;


Would it be okay to omit the GET /{conversationId} API?

seung-00 · 2026-10-18T02:14:56Z

+  const toConversation = (conversation: ConversationSummary): AssistantConversation => {
+    return {
+      id: conversation.id,
+      title: conversation.title,
+      ownerId: conversation.ownerId,
+      canSendMessage: conversation.canSendMessage,
+      updatedAt: conversation.updatedAt
+    };
+  };


Could we simplify this to:
const toConversation = (conversation: ConversationSummary): AssistantConversation => ({ ...conversation });

Also, are these types intended to separate the server response from the UI model? If so, could we name this function more clearly to reflect that?

seung-00 · 2026-10-18T02:38:51Z

@voidmatcha
I might be missing something, but would it be simpler to separate the conversation REST APIs from WebSocket streaming(openRun)? The REST calls seem similar to our other APIs, but coupling them with WebSocket streaming adds complexity.

For example, I’m not sure the REST calls need the same lifecycle handling in scopeTransport as openRun. Also, createAssistantTransport requires a socket even when the caller only needs the REST APIs.

voidmatcha · 2026-10-18T03:07:33Z

@seung-00 Thank you for the thoughtful review. I separated the conversation REST API from WebSocket runs. createAssistantConversationApi() handles listing, creating, and deleting conversations and fetching messages without a socket. socketRun() sends the message and consumes run events. I also removed scopeTransport, which managed both paths together.

I removed AbortSignal from the REST contract along with that shared lifecycle handling. The REST client therefore no longer suppresses late responses or 401/405 auth callbacks. When the panel is connected, its caller will need to check that responses and auth callbacks still belong to the current note and session. socketRun() retains its AbortSignal so the caller can stop consuming events, for example after navigating to another note. It does not cancel a run already accepted by the server.

The current frontend flow needs GET {apiBase}/notes/{noteId}/conversations and GET {apiBase}/notes/{noteId}/conversations/{conversationId}/messages?limit=50, with cursor for older messages. It does not use the single-conversation GET endpoint, so I left that endpoint out of the frontend contract.

I renamed the server response type to ConversationMetadataResponse and the conversion function to toAssistantConversation to make the boundary with the UI model explicit. updatedAt is used to order the list and remains in the UI model. It currently has no noteId or createdAt, so the conversion copies only its declared fields instead of spreading the entire server response.

Align the temporary integration branch with PR #5563's split conversation API and run stream. Preserve the assembled Assistant UI from the existing integration branch. Confidence: high Scope-risk: fixture panel work based on the old transport needs the new contract Not-tested: browser end-to-end Assistant flow

tbonelee · 2026-10-18T07:07:34Z

Merged into master (d01a1c3).

voidmatcha changed the base branch from temp/seung-00/assistant-transport-base to branch-seung-00-assistant-transport-base-temp October 9, 2026 01:35

voidmatcha closed this Oct 9, 2026

voidmatcha reopened this Oct 9, 2026

voidmatcha mentioned this pull request Oct 9, 2026

AI Assistant - integrated frontend seung-00/zeppelin#1

Open

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch 2 times, most recently from 2aaa236 to b75de05 Compare October 9, 2026 09:09

voidmatcha changed the base branch from branch-seung-00-assistant-transport-base-temp to branch-seung-00-assistant-transport-clean-temp October 9, 2026 09:09

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from b75de05 to c470802 Compare October 9, 2026 09:13

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from b772a8d to 9f119fc Compare October 10, 2026 00:50

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from 0c3b303 to c41de73 Compare October 10, 2026 00:50

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from 9f119fc to b0b71a0 Compare October 10, 2026 08:27

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from c41de73 to 3af8991 Compare October 10, 2026 08:27

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from b0b71a0 to fc57755 Compare October 10, 2026 08:37

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from 3af8991 to 3bcb8e2 Compare October 10, 2026 08:37

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from fc57755 to 404c586 Compare October 10, 2026 13:40

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from 3bcb8e2 to e3e2119 Compare October 10, 2026 13:40

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from 404c586 to e345f98 Compare October 10, 2026 15:44

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from e3e2119 to c221c82 Compare October 10, 2026 15:45

voidmatcha changed the title ~~[ZEPPELIN-6742] Connect the Assistant frontend to conversation REST and WebSocket APIs~~ [ZEPPELIN-6742] Connect the AI Assistant frontend to conversation REST and WebSocket APIs Oct 10, 2026

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from c221c82 to e4880f9 Compare October 11, 2026 04:28

miinhho reviewed Oct 11, 2026

View reviewed changes

voidmatcha force-pushed the branch-seung-00-assistant-transport-clean-temp branch from 7b16eb1 to 3e95adf Compare October 11, 2026 11:31

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from e4880f9 to 6de3a98 Compare October 11, 2026 11:31

tbonelee mentioned this pull request Oct 15, 2026

[ZEPPELIN-6741] Define shared AI Assistant UI contracts and message history behavior #5561

Merged

3 tasks done

voidmatcha mentioned this pull request Oct 15, 2026

[ZEPPELIN-6733] Add AI assistant chat to notebooks (server-side) #5547

Merged

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from 698542f to a3acd8e Compare October 15, 2026 15:43

seung-00 reviewed Oct 16, 2026

View reviewed changes

Connect assistant REST and WebSocket transport

c2ab3eb

voidmatcha changed the base branch from master to branch-voidmatcha-assistant-storybook-temp October 16, 2026 23:39

voidmatcha changed the base branch from branch-voidmatcha-assistant-storybook-temp to master October 16, 2026 23:39

tbonelee reviewed Oct 17, 2026

View reviewed changes

voidmatcha added 12 commits October 17, 2026 23:32

Share Assistant slot type with the sidebar shell

8ae45d3

Preserve Assistant disconnect state on rejected retries

1161409

Ignore history responses older than an Assistant disconnect

5740ccd

Preserve Assistant rounds in conversation transport

52ce842

Consume segment-only assistant history contract

7b50b6e

Align Assistant transport with server contract

1fad6cd

[ZEPPELIN-6742] Block duplicate assistant sends during active runs

8301c5e

[ZEPPELIN-6742] Drop the unused redirect location from Assistant auth…

d098067

… errors

[ZEPPELIN-6742] Simplify Assistant run tracking to the request being …

42f4565

…read

[ZEPPELIN-6742] Drop the unused Assistant run-state contract

a5127fe

[ZEPPELIN-6742] Retire assistant transport scopes after note changes

23880cd

[ZEPPELIN-6742] Preserve conversation titles in transport requests

34034fc

voidmatcha force-pushed the voidmatcha/assistant-v2-6-transport branch from 9df7e4d to 34034fc Compare October 17, 2026 14:32

seung-00 reviewed Oct 18, 2026

View reviewed changes

voidmatcha added 2 commits October 18, 2026 12:06

[ZEPPELIN-6742] Separate Assistant REST API from socket runs

765c905

[ZEPPELIN-6742] Clarify Assistant conversation response mapping

4fedd27

seung-00 approved these changes Oct 18, 2026

View reviewed changes

tbonelee approved these changes Oct 18, 2026

View reviewed changes

tbonelee merged commit d01a1c3 into apache:master Oct 18, 2026
41 of 42 checks passed

Conversation

voidmatcha commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is this PR for?

What type of PR is it?

Todos

What is the Jira issue?

How should this be tested?

Screenshots (if appropriate)

Questions:

Uh oh!

voidmatcha commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miinhho left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miinhho Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miinhho Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seung-00 Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tbonelee Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

voidmatcha commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seung-00 commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

voidmatcha commented Oct 18, 2026

Uh oh!

Uh oh!

tbonelee commented Oct 18, 2026

voidmatcha commented Oct 9, 2026 •

edited

Loading

voidmatcha commented Oct 9, 2026 •

edited

Loading

miinhho left a comment •

edited

Loading

miinhho Oct 11, 2026 •

edited

Loading

voidmatcha Oct 11, 2026 •

edited

Loading

miinhho Oct 11, 2026 •

edited

Loading

voidmatcha Oct 11, 2026 •

edited

Loading

voidmatcha Oct 16, 2026 •

edited

Loading

voidmatcha Oct 16, 2026 •

edited

Loading

seung-00 Oct 16, 2026 •

edited

Loading

voidmatcha Oct 16, 2026 •

edited

Loading

tbonelee Oct 17, 2026 •

edited

Loading

voidmatcha commented Oct 17, 2026 •

edited

Loading

seung-00 commented Oct 18, 2026 •

edited

Loading