[voidmatcha]

What is this PR for?

Define the shared types and message history behavior used by the Assistant UI and its host. This gives subsequent UI work a common contract to build against.

Depends on #5558.

What type of PR is it?

Improvement

Todos

• Merge [ZEPPELIN-6738] Upgrade React to 19 and fix shared host integration #5558 before this PR
• Rebase onto master and retarget this PR to master before merging
• Confirm CI results

What is the Jira issue?

ZEPPELIN-6741

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/messageHistory.spec.ts

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]

This PR defines the types shared by the Assistant UI and its host, and adds the conversion from stored message history to visible UI messages. The current diff is +211/-0 across five files. Excluding 63 lines in *.spec.* tests, the review diff is +148/-0. There is no lockfile change.

This depends on #5558. Review and approval can happen now, but I will wait for #5558 to merge, then rebase this branch onto the latest master and retarget the PR to master before merging it.

[voidmatcha]

Rebased onto master after #5558 merged to remove duplicated prerequisite changes. This PR now contains only its five intended files. The relevant local checks passed.

[tbonelee]

The most common page boundary is a question at the end of the earlier page and its answer at the start of the later one, but no test covers it. All tests still pass after removing last?.role === 'assistant' && from joinPages, which would merge the question into the answer. How about adding this case?

Suggested change

	expect(joinPages(earlier, later)).toEqual([...earlier, ...later]);
	expect(joinPages(earlier, later)).toEqual([...earlier, ...later]);
	expect(joinPages([later[0]], [later[1]])).toEqual(later);

[tbonelee]

When one answer spans several rounds (text, tool, text, tool), this shape merges them into a single content and a single toolCalls, so the order between text and tools is lost. The server history keeps that order, and the Direction in the frontend proposal (a renderer per tool inside the action log, the approval flow) may later need the answer shown step by step. Changing it then would change the shape of this contract, and the transport and UI along with it. How about keeping each round as segments instead of merging them, and joining them in the current UI? If merging is intended, could you share why?

[voidmatcha]

Thanks for the review. I updated the history model to preserve Assistant rounds as ordered segments, matching how the server stores them. I also removed the name field from tool_call.done, which the server does not send, and added tests for a question/answer split across page boundaries and overlapping pages. The focused unit tests, TypeScript check, and ESLint passed locally. The follow-up transport PR #5563 has been updated to use the same contract.

[tbonelee]

content and toolCalls can be derived from segments, so storing them as well lets them drift apart, as the input of the overlapping page test already does. How about dropping both fields, keeping only the rounds, and deriving them where needed?

export interface AssistantRound { id: string; content: string; toolCalls: AssistantToolCallRef[] }
export interface AssistantAnswerMessage { id: string; role: 'assistant'; rounds: AssistantRound[] }
export const answerText = (answer: AssistantAnswerMessage) =>
  answer.rounds.map(round => round.content).filter(Boolean).join('\n\n');

[seung-00]

Do these fields need to be optional?

[seung-00]

Should this be cursor?

See MessagesResponse.java.

[seung-00]

The server currently expects this field to be named content.

[seung-00]

It looks like cancellation isn't supported on the server side.

[seung-00]

The server’s listMessages() returns messages newest first, but this comment says “oldest first.” Should these match?
For example, assuming m5 is the newest message, the server returns [m5, m4, m3].

[voidmatcha]

@seung-00 Thank you for the thorough review. I removed the duplicated fields and aligned the request and response contracts with the server. #5563 converts the server’s newest-first messages to chronological order for the UI. The ordering and client-only abort behavior are documented and covered by tests.

[seung-00]

Just for reference, the server wraps the event data in payload. See AssistantEventPayload

Also, run.failed provides an error status rather than a message field.
For example:

{
  "conversationId": "...",
  "type": "run.failed",
  "payload": {
    "runId": "...",
    "error": {
      "status": 500
    }
  }
}

We could add a code for more specific handling later if needed.

[voidmatcha]

Thanks for the clarification. AssistantRunEvent is the UI-facing event, not the raw WebSocket event. The follow-up transport in #5563 reads payload.error.status and maps it to the message field; this is covered by its tests.

[seung-00]

When would this type be used?

[voidmatcha]

This type is for the revealParagraph callback planned in ZEPPELIN-6749. The Angular host would report whether a linked paragraph was scrolled into view, was already visible, or could not be found, and the React panel would announce the missing case. Since it is not consumed in this PR, I removed the declaration here and will define the result type alongside that callback.

[seung-00]

Could we make the return value more explicit? Spreading later could ignore some of earlier’s fields, such as toolCalls.

[voidmatcha]

Thanks for the careful review. toolCalls live on each segment, so the existing merge retains the calls from both pages. I agree that the top-level merge policy should be explicit, so I replaced ...later with id, role, and segments. All five message-history tests pass.

[tbonelee]

Merged into master (c10a4a8).