[Kinfe123]

Problem

Developers using assistant-ui with Convex Agent need a working example that connects Convex's reactive message history and streaming to a composable chat interface.

Closes #406.

Change

Add assistant-ui Chat at /chat-assistant-ui alongside the existing examples. The page includes a text composer, streamed Markdown, expandable reasoning and tool results, copy and scroll controls, paginated history, cancellation, and new conversations.

useConvexRuntime feeds useUIMessages into useExternalStoreRuntime; a small converter uses Convex's stable message key across streaming and persistence. The existing streamOneShot action supplies the send lifecycle, including the interval before the first stream delta. Stop uses the existing abortStreamByOrder mutation once a stream is available. Failed sends retain the prompt for recovery. New-conversation failures show an alert while preserving the current conversation, and pending creation disables repeat requests.

The route loads lazily. The messages and streaming docs list it alongside the existing React examples and link to its runtime hook and setup guide. The README explains the mapping, server-side credential setup, and scope: text input with the story agent, with uploads and tool approval covered by the existing examples. User messages appear when saved; the existing Streaming Chat example remains the reference for optimistic sending.

Verification

• npm run build
• npm test — 42 files, 473 tests passed, including 15 new converter/runtime/page tests
• The new-conversation regression tests fail with the original uncaught handler and pass with the fix. The real Cancel primitive stays disabled before a stream exists, ignores clicks then, and enables cancellation once a stream arrives.
• npm run typecheck
• npm run lint
• npx prettier --check example/ui/chat/ChatAssistantUI.tsx example/ui/chat/ChatAssistantUI.test.tsx example/ui/chat/assistant-ui/useConvexRuntime.test.tsx docs/streaming.mdx package.json package-lock.json
• cd example && npx vite build
• jsdom@26.1.0 declares Node >=18, preserving the package's Node >=22 range; its DOM smoke test also passes on local Node 18.18.2.
• Browser checks against an isolated local Convex deployment using real OpenAI gpt-4o-mini: initial story and tool call, keyboard submission, follow-up context and Markdown, reload persistence, and stopping a response while retaining partial text.
• Verified a new conversation clears the previous one, a 390px viewport remains usable, and pagination loads all 14 seeded local history messages without duplicates.

The production build reports its large-chunk and shared dynamic-import warnings. Provider credentials were configured only on the local backend and are absent from the change.

Public surface

Example frontend, messages/streaming docs, setup documentation, development dependencies, and lockfile only. No published package API or backend protocol changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: convex/coderabbit/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 048d3c10-a72e-4fc9-a8e4-be3a25d88c89

📥 Commits

Reviewing files that changed from the base of the PR and between e4266e7 and ba4cbfd.

📒 Files selected for processing: 1

• example/ui/chat/assistant-ui/Thread.tsx

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

Adds a routed assistant-ui chat example backed by Convex message conversion and runtime integration. The example supports streaming, Markdown, reasoning, tool results, approvals, history pagination, and cancellation. Approval submission now schedules response continuation when all decisions in a step are resolved. The client no longer triggers continuation. Tests and documentation cover the example and the updated approval flow.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant submitApproval
  participant ThreadMessages
  participant ScheduledFunctions
  participant generateResponse
  Client->>submitApproval: Submit approval decision
  submitApproval->>ThreadMessages: Load up to 100 messages and check decisions
  submitApproval->>ScheduledFunctions: Schedule generateResponse when all decisions are resolved
  ScheduledFunctions->>generateResponse: Continue from the latest approval decision

Loading

Suggested reviewers: robelest

Priority: ➖ Normal

Change: Feature

Merge Risk: ⚪ Minimal · up to ba4cb

This change adds an example chat page and moves approval continuation into the server-side approval flow. No actionable merge-blocking risk was identified in the supplied context.

Pre-merge checks: 2 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Linked Issues check		The new assistant-ui example satisfies the requested behavior in [#406], including the route, Convex-backed runtime, composer, streamed content, tool results, history, and cancellation. However, [#406…	Remove the approval-flow implementation, approval test, ChatApproval changes, and unrelated docs/tool-approval.mdx changes. Alternatively, expand [#406] with a direct coding requirement for this approval-flow change.
Out of Scope Changes check		The assistant-ui route, runtime, UI, focused tests, dependencies, and related setup or streaming documentation are in scope for [#406]. The changes to example/convex/chat/approval.ts, `example/conve…	Remove the approval continuation implementation, its test, the existing ChatApproval changes, and the related tool-approval documentation changes unless [#406] is expanded to cover them.

Passed checks: 2 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: adding an assistant-ui chat interface example.
Description check		The description directly explains the new assistant-ui chat example, its functionality, implementation, documentation, testing, and scope.

Full details: Linked Issues check

Explanation

The new assistant-ui example satisfies the requested behavior in [#406], including the route, Convex-backed runtime, composer, streamed content, tool results, history, and cancellation. However, [#406] limits the work to the example frontend, development dependencies, focused tests, and setup documentation. This PR also changes the backend approval flow in example/convex/chat/approval.ts and adds example/convex/chat/approval.test.ts. It also changes the existing approval client and tool-approval documentation. These changes are not required by the linked issue.

Resolution

Remove the approval-flow implementation, approval test, ChatApproval changes, and unrelated docs/tool-approval.mdx changes. Alternatively, expand [#406] with a direct coding requirement for this approval-flow change.

Full details: Out of Scope Changes check

Explanation

The assistant-ui route, runtime, UI, focused tests, dependencies, and related setup or streaming documentation are in scope for [#406]. The changes to example/convex/chat/approval.ts, example/convex/chat/approval.test.ts, example/ui/chat/ChatApproval.tsx, and docs/tool-approval.mdx modify the existing approval continuation architecture. The linked issue does not request this backend or existing-example change.

Resolution

Remove the approval continuation implementation, its test, the existing ChatApproval changes, and the related tool-approval documentation changes unless [#406] is expanded to cover them.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

example/ui/chat/assistant-ui/Thread.tsx

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

All reported issues were addressed across 10 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@convex-dev/agent@407

commit: ba4cbfd

[robelest]

@cubic-dev-ai review

[cubic-dev-ai]

@cubic-dev-ai review

@robelest I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 15 files

<sub>Tip: Get a Slack DM when cubic finishes reviewing your PRs. Connect Slack

Re-trigger cubic</sub>