[fix] Say why the first turn is parked when no provider key exists [AGE-4232]

[ashrafchowdury]

Context

Sign in to a workspace with no AI provider connected, type a first message into the Home composer, and press Enter. The message appears as a sent bubble, a "..." loader appears under it, and it never stops. No run request is ever sent, so nothing is waiting on the server.

The seed is parked on purpose. useFirstRunSeed holds the send while the connect-model gate is active, and releases it the moment a key lands. That part works. What was missing is any sign of it: TranscriptPlaceholder rendered the assistant loader unconditionally for a pending first turn, so a parked seed and a running seed looked identical.

The "+ new session" tab stayed locked for the same reason. Onboarding holds it until the founding run settles, and it waits on a run status. A gated project never produces a run, so the lock never lifted and the user could not start a second chat to get out.

Changes

The pending first turn now branches on the gate. canStart was already passed into TranscriptPlaceholder (it is !modelBlocked at the call site), so no new state was needed.

Before, for a parked seed:

[ your message                    ]
                        ( ... )     <- forever

After:

[ your message                    ]
  This agent needs a model provider key
  Your message is waiting. It sends as soon as a key is connected.
  [ Set up model providers ]

The new ConnectModelCallout sits in the same borderless ChatBubble the loader used, so placement and width are unchanged. Its button writes openProviderDrawerRequestAtom, the same hand-off the failed-run callout already uses, and ConnectModelBanner opens the drawer as it does today. No new plumbing, and the existing connect, unlock, and auto-send sequence is untouched.

It is deliberately not the failed-run callout. Nothing failed here, because nothing ran.

For the lock, useAgentOnboarding now treats an active gate as a settled first run, alongside error. Same rule: never trap the user. The candidate atom is swapped for an inert one once the lock is out of play, so a plain playground does not subscribe to the query-backed candidate sources.

Tests

• ConnectModelCallout.test.tsx, static-render, same shape as the existing AgentMessage.runError.test.tsx.
• pnpm lint-fix and tsc clean. The 5 existing RunErrorBody tests still pass.
• Not verified in the running app. The dev server did not finish a cold Turbopack compile in the time available, so this is verified by types, lint, and unit tests only. The QA steps below are worth running before merge.

What to QA

• In a workspace with no provider connected, type a first message on Home and press Enter. The thread shows the callout under your message, not a spinner.
• Click "Set up model providers" on that callout. The providers drawer opens.
• Save a key from that drawer without leaving the page. The callout goes away and your held message sends by itself.
• With the callout up, click "+ new session". It is enabled, and a second session opens.
• Regression: in a workspace that already has a key, send a first message from Home. You still get the loader, and the run starts as before.
• Regression: reloading while the callout is up still loses the typed message and shows "History no longer available". That is unchanged and out of scope here (issue (bug) With no provider key connected, the first message hangs on a "..." that never ends #6441 defers persisting the parked seed).

Closes #6441

[linear-code]

AGE-4232

[vercel]

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

Project	Deployment	Actions	Updated
agenta-documentation	Ready	Preview	Sep 2, 2026 7:07am UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Team

Run ID: 4a3caf5d-603f-4ef6-aaee-635eab8a643b

📥 Commits

Reviewing files that changed from the base of the PR and between 553fb9d and 7e2f827.

📒 Files selected for processing (4)

• web/oss/src/components/AgentChatSlice/components/ConnectModelCallout.test.tsx
• web/oss/src/components/AgentChatSlice/components/ConnectModelCallout.tsx
• web/oss/src/components/AgentChatSlice/components/TranscriptPlaceholder.tsx
• web/oss/src/components/pages/agent-home/PlaygroundOnboarding/useAgentOnboarding.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 4 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added an in-chat callout when a model provider must be connected before an agent message can run.
  • Added a “Set up model providers” action that opens provider settings.
  • Pending messages now clearly indicate they will be sent after a provider is connected.

• Bug Fixes

  • Improved new-session onboarding for projects without a runnable model, allowing setup to continue instead of remaining locked.
  • Replaced the indefinite loading indicator with actionable guidance when model setup is required.

Walkthrough

The onboarding hook now releases the new-session lock when the connect-model gate is active. The transcript replaces the indefinite first-turn loader with a provider setup callout and preserves the loader when a turn can start. Tests cover the callout text and setup action.

Changes

Connect-model onboarding

Layer / File(s)	Summary
Settle the onboarding gate web/oss/src/components/pages/agent-home/PlaygroundOnboarding/useAgentOnboarding.ts	The hook observes model candidates, computes modelGateActive, and settles the first-run state when the gate prevents a founding run.
Render provider setup feedback web/oss/src/components/AgentChatSlice/components/ConnectModelCallout.tsx, web/oss/src/components/AgentChatSlice/components/TranscriptPlaceholder.tsx, web/oss/src/components/AgentChatSlice/components/ConnectModelCallout.test.tsx	The optimistic assistant bubble renders ConnectModelCallout when canStart is false. The callout requests the provider drawer and explains that the message is waiting. Tests verify its rendered text and setup affordance.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 7e2f8

This localized change explains when a first message is waiting for a provider key and unlocks starting another session while preserving the existing setup and send flow; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant PlaygroundOnboarding
  participant TranscriptPlaceholder
  participant ConnectModelCallout
  participant ProviderDrawer
  PlaygroundOnboarding->>PlaygroundOnboarding: detect active connect-model gate
  PlaygroundOnboarding->>TranscriptPlaceholder: set canStart=false
  TranscriptPlaceholder->>ConnectModelCallout: render waiting callout
  ConnectModelCallout->>ProviderDrawer: request provider setup
  ProviderDrawer-->>ConnectModelCallout: provider key connected
  TranscriptPlaceholder->>TranscriptPlaceholder: restore loading state and held turn

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #6441 by replacing the indefinite loader with an in-thread provider-key callout, exposing provider setup, preserving automatic send after connection, and unlocking the new-se…
Out of Scope Changes check	✅ Passed	The changed component, onboarding logic, and tests are directly related to issue #6441. No unrelated code changes are described.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.
Title check	✅ Passed	The title clearly summarizes the main change: explaining why the first turn is parked when no provider key exists. The issue reference is relevant.
Description check	✅ Passed	The description directly explains the parked first-turn behavior, the new provider-key callout, the provider drawer flow, and the session unlock change.

Full details: Linked Issues check

Explanation

The changes satisfy issue #6441 by replacing the indefinite loader with an in-thread provider-key callout, exposing provider setup, preserving automatic send after connection, and unlocking the new-session tab when the connect-model gate is active.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/connect-model-first-turn-hang-6441

---

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.}