Skip to content

✨ feat(onboarding): simplify first screen and defer topic creation to first send#15090

Merged
AmAzing129 merged 3 commits into
canaryfrom
feat/lobe-9337-onboarding-step1-optimization
May 22, 2026
Merged

✨ feat(onboarding): simplify first screen and defer topic creation to first send#15090
AmAzing129 merged 3 commits into
canaryfrom
feat/lobe-9337-onboarding-step1-optimization

Conversation

@Innei

@Innei Innei commented May 21, 2026

Copy link
Copy Markdown
Member

πŸ’» Change Type

  • ✨ feat
  • πŸ› fix
  • ♻️ refactor
  • πŸ’„ style
  • πŸ‘· build
  • ⚑️ perf
  • βœ… test
  • πŸ“ docs
  • πŸ”¨ chore

πŸ”— Related Issue

Fixes LOBE-9337

πŸ”€ Description of Change

Two compounding issues on the /onboarding/agent first screen:

  1. Visual overload. The Welcome card was buried under a markdown explainer, three guidance blocks (Name Me / Get to Know You / Grow with You), and a footer β€” pushing the only real first action (naming the agent) below the fold.
  2. Misleading loading + Welcome flash. Every entry showed a full-screen BrandTextLoading while getOrCreateOnboardingState was in-flight, even though the title/subtitle are static i18n. Returning users then briefly saw the Welcome before their transcript loaded, because the frontend had no way to distinguish a fresh topic from a returning one until messagesMap populated.

Behind both is an architectural smell: getOrCreateOnboardingState is a GET that writes (creates a topic via ensureTopic), forcing the first paint to wait on a write and leaving stray empty topics for users who bounce.

What this PR does:

  • Welcome cleanup β€” Welcome.tsx / Welcome.mobile.tsx now render only LobeMessage (avatar + title + subtitle). The markdown explainer, the 3-card grid, the footer line, and the divider are removed.
  • Split read from write on the server β€” new OnboardingService.getBootstrapState() is genuinely read-only (no discoveryStartUserMessageCount baseline write, no topic creation). It returns { topicId: string | null, hasMessages: boolean, ... } so the UI can branch correctly. The old getOrCreateState is kept for now to avoid touching unrelated callers.
  • Atomic first-send mutation β€” OnboardingService.sendOnboardingFirstMessage({ agentId, welcomeContent }) opens a transaction, takes pg_advisory_xact_lock(hashtext(${userId}:${agentId})) to serialize concurrent calls, ensures the topic, and inserts the welcome assistant message only if no assistant message already exists in the topic (using a new findFirstAssistantInTopic helper). The user + assistant pair continues to flow through the existing sendMessage pipeline.
  • Fresh-state UX β€” full-screen BrandTextLoading is gone. The Welcome shell renders immediately from i18n; ChatInput is visible from the first paint and shows its skeleton-style send area via isConfigLoading until backend hydration completes (`isInputReady = !isLoading`).
  • Returning-user UX β€” when hasMessages: true, the page skips Welcome entirely. ChatList's existing SkeletonList covers the brief messages-fetch window.
  • Double-submit safety β€” useOnboardingFirstMessage holds a firstSendInFlightRef latch covering the whole sendOnboardingFirstMessage β†’ hydrate β†’ useChatStore.sendMessage chain. Second invocation awaits the in-flight promise rather than dispatching its own send. The second-step send dispatches directly into useChatStore.getState().sendMessage with an explicit context: { agentId, topicId: serverTopicId } so it cannot accidentally enter sendMessageInServer's new-topic creation branch via a stale conversation-store context. The wrapping ConversationStore.sendMessage is short-circuited by returning false from onBeforeSendMessage.
  • New MessageModel.hasTopicMessages(topicId) β€” SELECT id ... WHERE userId AND topicId LIMIT 1, scoped by user, used to drive the hasMessages branch.
  • i18n cleanup β€” removed agent.welcome.guide.* and agent.welcome.footer (UI-only keys); kept agent.welcome (still used as the persisted opener content) and agent.welcome.suggestion.* (NameSuggestions). Added agent.input.preparing for the gated submit tooltip.

Design spec (Revisions 1–3) lives in docs/superpowers/specs/2026-05-22-onboarding-agent-step1-design.md (local-only, gitignored).

πŸ§ͺ How to Test

  • Tested locally
  • Added/updated tests
  • No tests needed

Manual:

  1. Fresh user β†’ /onboarding/agent: Welcome (title + subtitle only) shows immediately, no full-screen loader. ChatInput frame is visible; the send area shows the skeleton until backend is ready.
  2. Type something and hit Enter: server returns { topicId, messages: [welcome] }, the page hydrates locally, and the existing send pipeline streams the assistant reply.
  3. Reload mid-conversation: no Welcome flash β€” SkeletonList shows briefly, then the transcript.
  4. Rapid double-click submit (or two tabs): only one topic + one welcome end up in the DB.

Automated:

  • OnboardingService 21/21 βœ“ β€” covers getBootstrapState (fresh / returning / no baseline write) and sendOnboardingFirstMessage (happy path / idempotency / advisory lock).
  • Conversation 10/10 βœ“ β€” covers the hasMessages-driven welcome suppression and isInputReady β†’ isConfigLoading wiring.
  • MessageModel stats 32/32 βœ“ β€” covers new hasTopicMessages (incl. userId scoping) and findFirstAssistantInTopic.
  • Adjacent Onboarding modules (5 files) 15/15 βœ“.
  • routes/onboarding/agent 8/8 βœ“.

πŸ“Έ Screenshots / Videos

Before After
Full-screen brand loader β†’ Welcome with markdown + 3-card grid + footer + dashed divider Immediate Welcome shell (title + subtitle), ChatInput frame visible, submit gated by skeleton until ready

πŸ“ Additional Information

  • Cross-tab user-message dedup is explicitly out of scope and matches existing behavior for any conversation.
  • Other locales (tr-TR / fr-FR / etc.) still contain the deleted agent.welcome.guide.* and agent.welcome.footer entries as harmless orphans; `pnpm i18n` will sweep them.
  • The old `getOrCreateOnboardingState` query and `getOrCreateState` service method are intentionally retained for now; safe to remove in a follow-up once we're sure no external caller depends on the legacy shape.

… first send

Cuts the noisy welcome guidance cards and the misleading full-screen
BrandTextLoading on entry. New flow:

- Welcome shell renders immediately from i18n β€” title + subtitle only.
- ChatInput frame is visible from the first paint; submit is gated via
  `isConfigLoading` until backend bootstrap + builtin agent are ready.
- Bootstrap no longer creates an empty topic. Topic + welcome opener
  are created atomically on first send via a new mutation, guarded by
  a pg advisory lock + welcome-existence idempotency check.
- Returning users with messages skip Welcome entirely; ChatList's
  existing skeleton covers the brief fetch window.

User + assistant messages still flow through the existing sendMessage
pipeline. A client-side latch in `useOnboardingFirstMessage` plus an
explicit `context.topicId` handoff prevent double-submit from producing
duplicate user messages or accidentally entering the new-topic branch.

Fixes LOBE-9337

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @Innei, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

@vercel

vercel Bot commented May 21, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
lobehub Ready Ready Preview, Comment May 21, 2026 6:44pm

Request Review

@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. feature:agent-builder Agent builder labels May 21, 2026
@codecov

codecov Bot commented May 21, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.34356% with 19 lines in your changes missing coverage. Please review.
βœ… Project coverage is 70.75%. Comparing base (874cf39) to head (12c10b8).
⚠️ Report is 8 commits behind head on canary.

Additional details and impacted files
@@             Coverage Diff             @@
##           canary   #15090       +/-   ##
===========================================
- Coverage   89.65%   70.75%   -18.91%     
===========================================
  Files         846     3102     +2256     
  Lines      102258   309058   +206800     
  Branches     9020    33468    +24448     
===========================================
+ Hits        91679   218669   +126990     
- Misses      10412    90222    +79810     
  Partials      167      167               
Flag Coverage Ξ”
app 61.40% <86.42%> (?)
database 92.16% <100.00%> (+0.01%) ⬆️
packages/agent-runtime 80.48% <ΓΈ> (ΓΈ)
packages/builtin-tool-lobe-agent 19.87% <ΓΈ> (ΓΈ)
packages/context-engine 84.07% <ΓΈ> (ΓΈ)
packages/conversation-flow 91.28% <ΓΈ> (ΓΈ)
packages/file-loaders 87.89% <ΓΈ> (ΓΈ)
packages/memory-user-memory 75.01% <ΓΈ> (ΓΈ)
packages/model-bank 99.99% <ΓΈ> (ΓΈ)
packages/model-runtime 83.63% <ΓΈ> (ΓΈ)
packages/prompts 71.60% <ΓΈ> (ΓΈ)
packages/python-interpreter 92.90% <ΓΈ> (ΓΈ)
packages/ssrf-safe-fetch 0.00% <ΓΈ> (ΓΈ)
packages/types 35.20% <ΓΈ> (ΓΈ)
packages/utils 88.02% <ΓΈ> (ΓΈ)
packages/web-crawler 87.74% <ΓΈ> (ΓΈ)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components Coverage Ξ”
Store 68.01% <ΓΈ> (βˆ…)
Services 54.63% <28.57%> (βˆ…)
Server 72.01% <89.92%> (βˆ…)
Libs 56.39% <ΓΈ> (βˆ…)
Utils 85.01% <ΓΈ> (-8.47%) ⬇️
πŸš€ New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • πŸ“¦ JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

πŸ’‘ Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8b68dfbee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with πŸ‘.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/server/services/onboarding/index.ts Outdated
@AmAzing129 AmAzing129 merged commit 029d442 into canary May 22, 2026
35 checks passed
@AmAzing129 AmAzing129 deleted the feat/lobe-9337-onboarding-step1-optimization branch May 22, 2026 03:10
arvinxx added a commit that referenced this pull request May 29, 2026
# πŸš€ LobeHub Release (20260528)

**Release Date:** May 28, 2026  
**Since v2.2.0:** 220 merged PRs Β· 15 contributors

> This cycle brings heterogeneous "platform agents" you can dispatch to
local or remote devices, a rebuilt onboarding flow, document-centric
chat, and a unified model-runtime error model β€” with new DeepSeek V4 and
Gemini 3.5 Flash support along the way.

---

## ✨ Highlights

- **More Hetero Agents (OpenClaw / Hermes)** β€” Create heterogeneous
agents and dispatch them to local or remote devices through the device
gateway, with an execution-target switcher in the composer and
persistent CLI sessions. (#15065, #15179, #15022)
- **iMessage on Desktop** β€” New iMessage setup and bridge on desktop,
plus bot attachments across every platform. (#15228, #15227, #15029)
- **Skills in the Composer** β€” Drag skill chips into chat, trigger
installed skills from the slash menu mid-line, and surface project-level
skills in the homogeneous agent runtime. (#15095, #15061, #15110)
- **New Models** β€” DeepSeek V4 Flash/Pro and Gemini 3.5 Flash across
providers, with thinking params for structured output and chat cost
estimates. (#15031, #15001, #15051, #14876)
- **Agent Runtime Observability** β€” OpenTelemetry GenAI semantic
conventions plus per-call generation tracing. (#15123, #15124)

---

## πŸ€– Agents & Heterogeneous Runtime

- **Platform agent creation** β€” OpenClaw/Hermes creation UI, device
guard, and remote dispatch backend. (#15065)
- **Execution-target switcher** β€” Pick local vs remote execution
directly in the composer; device-selection UX with actionable guidance.
(#15179, #15111)
- **CLI hetero dispatch** β€” OpenClaw/Hermes dispatch with persistent
sessions and a notify protocol. (#15022)
- **Gateway snapshot as source of truth** β€” Consume the gateway
`uiMessages` snapshot at step boundaries to keep chat state consistent.
(#15153, #15152)
- **Client sub-agent as a normal tool call** β€” Simplifies the sub-agent
execution path. (#15281)
- **Hermes agent chain** β€” Implements the Hermes agent chain logic.
(#15189)
- **Device registry** β€” TRPC endpoints to register, list, update, and
remove devices. (#15299)
- **Desktop device routing** β€” Route gateway agent runs through `lh
hetero exec`; restore `userId` in gateway dispatch and gate local-system
by execution target. (#15132, #15232)
- **Agent signals** β€” Anchor agent-signal receipts to messages and
isolate memory-agent messages into a child thread. (#14969, #14921)

---

## πŸš€ Onboarding

- **Simplified first screen** β€” Defer topic creation to first send.
(#15090)
- **Market Agent Picker** β€” Added as a classic onboarding step, with
template prefetch. (#14980, #15041)
- **Welcome guidance** β€” Show agent welcome guidance on first run.
(#15098)
- **Mobile** β€” Adapt agent onboarding UI and restore Classic-step
padding on mobile. (#15019, #15032)
- **Discovery** β€” Streamline discovery to a single profession question.
(#14987)
- **Analytics** β€” Track onboarding step events and create-agent modal
source. (#15133, #15028)

---

## πŸ“„ Documents, Pages & Knowledge

- **Thread chat in preview** β€” Embed thread chat in the document preview
portal. (#15216)
- **Non-markdown rendering** β€” Render non-markdown docs as a read-only
highlight. (#15272)
- **Multi-select** β€” Multi-select delete in the document tree. (#15125)
- **Page-agent streaming** β€” Preview `initPage` streaming arguments.
(#15039)
- **Per-agent topics** β€” Per-agent topic management page. (#15207)
- **Server-side category** β€” Derive document category server-side and
drop frontend predicates. (#15076)

---

## 🧩 Skills & Tools

- **Drag skill chips** β€” Drag skills into chat input and register
agent-document skills. (#15095)
- **Slash menu** β€” Installed skills appear in the slash menu with a
mid-line trigger. (#15061)
- **Project skills** β€” Recognize project-level skills in the homogeneous
agent runtime and surface them regardless of active device. (#15110,
#15177)
- **VFS archiving** β€” Archive oversized tool results to VFS instead of
truncating. (#15074)
- **@localfile mentions** β€” Drag folders into chat input as `@localFile`
mentions on desktop. (#15071)

---

## 🧠 Model Runtime & Providers

- **Error spec registry** β€” Unify error codes into a spec + pattern
registry, split `ProviderBizError` into finer codes, classify Cloud-only
codes via a tier digit, and add `DatabasePersistError`. (#15262, #15286,
#15278, #15279)
- **New models** β€” DeepSeek V4 Flash/Pro (opencode-go) and Gemini 3.5
Flash; DeepSeek V4 Pro on SiliconCloud. (#15031, #15001, #15017, #15267)
- **Structured output** β€” Thinking params for structured output, Bedrock
structured generation, and DeepSeek `generateObject` tool choice.
(#15051, #15174, #15054)
- **Cost** β€” Chat cost estimate support; preserve usage cost in custom
streams. (#14876, #15218)

---

## πŸ’¬ Chat & User Experience

- **Follow-up chips** β€” Extend follow-up chip suggestions to general
chat with scene-specific model config. (#15101, #14797)
- **Input drafts** β€” Persist unsent input drafts across tab switches and
prevent repeated draft restore. (#14992, #15024)
- **Command menu** β€” Order topic/message search by recency and promote
inline type filters. (#15094, #14986)
- **Zoom HUD** β€” Show a zoom-level HUD on Cmd +/βˆ’ and Cmd 0. (#15294)
- **Copy** β€” Unescape markdown escapes when copying user messages.
(#15253)

---

## πŸ–₯️ Desktop

- **App Nap fix** β€” Prevent App Nap from dropping the gateway WebSocket
during display sleep. (#14994)
- **File preview** β€” Preview `.cjs`/`.mjs`/no-extension files instead of
binary fallback and expand `~` when opening local files. (#15168,
#15284)
- **Cross-platform settings** β€” Open settings via main-window navigation
on Windows/Linux and restore the route after an update restart. (#15036,
#14922)
- **Token refresh** β€” Prevent frequent logout from token-refresh
retries. (#14928)

---

## πŸ“Š Observability

- **OTel GenAI** β€” Instrument Agent Runtime with OpenTelemetry GenAI
semantic conventions. (#15123)
- **Generation tracing** β€” Per-call `llm_generation_tracing` with a
pre-allocated tracingId and recordFeedback router. (#15124, #15146)
- **Error classification** β€” Persist `ERROR_CODE_SPECS` classification
on operation errors. (#15273)

---

## πŸ—ƒοΈ Database Migrations

- **Batch migrations** β€” Topic usage stats, push tokens,
`tasks.editor_data`, and document shares. (#15280)
- **Tracing & eval tables** β€” Add `llm_generation_tracing` and agent
eval experiment tables. (#15126)

> Self-hosted operators should run the database migration (`pnpm
db:migrate`, or restart with auto-migrate enabled) after upgrading. The
changes are additive and backwards-compatible.

---

## πŸ”’ Security & Reliability

- **Security:** Remove the `getPlaintextCred` tool to prevent plaintext
credential exposure. (#14998)
- **Security:** Prompt account selection for Google OAuth and add
`prompt=consent` to the OIDC authorization URL to fix missing refresh
tokens. (#15234, #15010)
- **Reliability:** Preserve streamed content across a mid-stream cancel.
(#15173)
- **Reliability:** Bound the Redis command timeout and configure the
Anthropic client timeout. (#15091, #15042)
- **Reliability:** Prevent infinite recursion in the assistant chain.
(#15288)

---

## πŸ‘₯ Contributors

Huge thanks to **15 contributors** who shipped **220 merged PRs** this
cycle.

@AnotiaWang Β· @sxjeru Β· @algojogacor Β· @hardy-one Β· @arvinxx Β· @Innei Β·
@tjx666 Β· @lijian Β· @AmAzing129 Β· @rdmclin2 Β· @neko Β· @cy948 Β·
@CanisMinor Β· @sudongyuer Β· @rivertwilight

Plus @lobehubbot and renovate[bot] for maintenance.

---

**Full Changelog**: v2.2.0...release/weekly-20260528
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature:agent-builder Agent builder size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants