[6764] fix(frontend): Distinguish runner-unavailable from a missing key

[li872]

Closes #6764

Summary

A successful subscription-status probe with runner: unavailable was treated as zero model candidates, so the playground asked users to add a provider key. That is the wrong fix when models come from a mounted subscription login. Keep the composer locked, but show a temporary runtime-outage message instead of the providers CTA.

resolveAgentModelCandidateSources now sets runnerUnavailable for that probe result when nothing else is runnable. connectModelGate stays off; composerBlocked still locks the composer. Shared modelComposerChrome copy:

• missing key → “Add your model provider key…” + providers CTA
• runner down → “The agent runtime is temporarily unreachable.” (no providers button)

Desktop ConnectModelBanner and mobile ConnectModelStrip both use that helper. When the probe later returns connected, the existing 15s refetch clears the outage without a full reload.

Tradeoff: a workspace that already has a vault key still gets candidates / unlocked composer while the runner is down (same as before). Only the empty-candidate case is reclassified.

Testing

Verified locally

• pnpm --filter @agenta/entities test:unit (1616 passed)
• pnpm --filter @agenta/chat test:unit (1026 passed)
• focused OSS banner/gate + mobile ConnectModelStrip tests
• lint + types check for entities, chat, oss, mobile

Added or updated tests

• successful runner: "unavailable" + empty vault must not activate connect-model copy
• connected runner with no pairs still does
• subscriptionError still reports status: "error" (not missing-key ready)

QA follow-up

• Stop the agent runner on a subscription-only workspace → outage banner, no providers button, composer locked
• Same on mobile /m
• Keyless + connected runner → still connect-model banner
• Restart runner → banner clears / composer unlocks without full reload

Demo

Before/after for runner: "unavailable" with no vault key (subscription-only workspace shape). Composer stays locked; providers CTA only on the missing-key path.

[vercel]

@li872 is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

✅ Thanks @li872! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features

  • Added distinct handling for unavailable model runners and missing provider setup.
  • Chat composers now show state-specific banners and placeholders.
  • Provider setup actions appear only when a provider key is required.
  • Runner availability is detected and surfaced in agent model status.

• Bug Fixes

  • Prevented unavailable runners from incorrectly showing provider setup prompts.

• Tests

  • Added coverage for runner availability, messaging, gating, and composer behavior.

Walkthrough

The change adds explicit runner-unavailable state to model candidate resolution, maps it to shared composer metadata, and updates OSS and mobile banners and placeholders. Tests cover candidate resolution, gate behavior, messaging, provider setup visibility, and unlocked states.

Changes

Runner-aware composer state

Layer / File(s)	Summary
Candidate source runner state web/packages/agenta-entities/src/workflow/state/agentModelCandidates.ts, web/packages/agenta-entities/tests/unit/agent-model-candidate-sources.test.ts	Candidate resolution reports runnerUnavailable when the subscription probe reports an unavailable runner with no candidates. Other states report false.
Shared composer state mapping web/packages/agenta-chat/src/hooks/useAgentModelKeyStatus.ts, web/packages/agenta-chat/tests/unit/hooks/useAgentModelKeyStatus.test.ts, web/oss/src/components/AgentChatSlice/hooks/useAgentModelKeyStatus.test.ts	The shared status exposes runnerUnavailable and composerBlocked. modelComposerChrome supplies state-specific messages, placeholders, and provider-setup visibility.
Composer surface integration web/oss/src/components/AgentChatSlice/components/*, web/oss/src/components/AgentChatSlice/AgentConversation.tsx, web/mobile/src/features/chat/*, web/mobile/tests/unit/ConnectModelStrip.test.tsx	OSS and mobile surfaces use shared composer metadata. Runner-unavailable states show outage copy without provider-key setup actions.

Priority: ➖ Normal

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

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant AgentRunner
  participant CandidateResolution
  participant useAgentModelKeyStatus
  participant ComposerSurface
  AgentRunner-->>CandidateResolution: runner unavailable probe result
  CandidateResolution->>useAgentModelKeyStatus: runnerUnavailable true
  useAgentModelKeyStatus->>ComposerSurface: locked state, outage message, placeholder
  ComposerSurface-->>ComposerSurface: hide provider setup action

Loading

Merge Risk: ⚪ Minimal · up to b719f

No merge-blocking behavior issue remains in the runner-availability composer changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 12 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: distinguishing an unavailable runner from a missing provider key.
Description check	✅ Passed	The description directly explains the runner-unavailable bug, the composer and CTA behavior, the shared helper changes, recovery behavior, and testing.
Linked Issues check	✅ Passed	The changes satisfy issue #6764. resolveAgentModelCandidateSources marks a successful runner: "unavailable" probe with no vault candidates as runnerUnavailable. connectModelGate keeps this sta…
Out of Scope Changes check	✅ Passed	The changed source files implement the issue #6764 state distinction and propagate it through desktop and mobile composer UI. The added tests verify the required state transitions and presentation. Th…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

web/mobile/src/features/chat/ConnectModelStrip.tsx (1)

12-12: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Reduce both comments to one short line. The checked-in frontend guidance applies to ConnectModelStrip.tsx and LiveConversation.tsx; shorten the multi-line comments at the cited locations.

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Advanced

Run ID: cf1c13b1-c1a4-415c-8bf6-386b52afe3d4

📥 Commits

Reviewing files that changed from the base of the PR and between e4008fa and b719f97.

⛔ Files ignored due to path filters (2)

• docs/pr-6764-demo/missing-key.png is excluded by !**/*.png
• docs/pr-6764-demo/runner-unavailable.png is excluded by !**/*.png

📒 Files selected for processing (12)

• web/mobile/src/features/chat/ConnectModelStrip.tsx
• web/mobile/src/features/chat/LiveConversation.tsx
• web/mobile/tests/unit/ConnectModelStrip.test.tsx
• web/oss/src/components/AgentChatSlice/AgentConversation.tsx
• web/oss/src/components/AgentChatSlice/components/AgentComposerDock.tsx
• web/oss/src/components/AgentChatSlice/components/ConnectModelBanner.test.tsx
• web/oss/src/components/AgentChatSlice/components/ConnectModelBanner.tsx
• web/oss/src/components/AgentChatSlice/hooks/useAgentModelKeyStatus.test.ts
• web/packages/agenta-chat/src/hooks/useAgentModelKeyStatus.ts
• web/packages/agenta-chat/tests/unit/hooks/useAgentModelKeyStatus.test.ts
• web/packages/agenta-entities/src/workflow/state/agentModelCandidates.ts
• web/packages/agenta-entities/tests/unit/agent-model-candidate-sources.test.ts

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