Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
fix(web): say which provider to connect when a bot chat can't start (#349)
Leoa280aa6c8fea
diff --git a/.changeset/signed-out-provider-chat-error.md b/.changeset/signed-out-provider-chat-error.mdnew file mode 100644index 000000000..d1b246701--- /dev/null+++ b/.changeset/signed-out-provider-chat-error.md@@ -0,0 +1,5 @@+---+"akeru-bot": patch+---++A bot chat now says when its provider isn't signed in, using the account's name and logo (for example "Claude is not connected"), and its Connect button opens that provider's settings page. Before, the chat showed "Provider instance 'claudeAgent' is not available." and asked you to send feedback.diff --git a/apps/mobile/src/features/threads/ThreadDetailScreen.tsx b/apps/mobile/src/features/threads/ThreadDetailScreen.tsxindex 0129f11c7..796541068 100644--- a/apps/mobile/src/features/threads/ThreadDetailScreen.tsx+++ b/apps/mobile/src/features/threads/ThreadDetailScreen.tsx@@ -18,7 +18,12 @@ import type {ServerProviderUnavailability,UserInputQuestion,} from "@akeru/contracts";-import { PROVIDER_DISPLAY_NAMES, ProviderDriverKind } from "@akeru/contracts";+import {+ defaultInstanceIdForDriver,+ PROVIDER_DISPLAY_NAMES,+ stockProviderAccountName,+ ProviderDriverKind,+} from "@akeru/contracts";import * as Haptics from "expo-haptics";import {memo,@@ -484,11 +489,15 @@ export const ThreadDetailScreen = memo(function ThreadDetailScreen(props: Thread(provider) => provider.instanceId === selectedInstanceId,);+ const selectedDriver = selectedProvider?.driver ?? ProviderDriverKind.make(selectedInstanceId);++ // Failure copy names a built-in instance by its account: "ChatGPT", not "Codex".const selectedProviderName =+ (selectedInstanceId === defaultInstanceIdForDriver(selectedDriver)+ ? stockProviderAccountName(selectedDriver, selectedProvider?.displayName)+ : undefined) ??selectedProvider?.displayName ??- PROVIDER_DISPLAY_NAMES[- selectedProvider?.driver ?? ProviderDriverKind.make(selectedInstanceId)- ] ??+ PROVIDER_DISPLAY_NAMES[selectedDriver] ??selectedInstanceId;const selectedProviderSkills = useMemo(diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.turnStart.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.turnStart.test.tsindex 9c0eb671d..21741f85e 100644--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.turnStart.test.ts+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.turnStart.test.ts@@ -317,6 +317,7 @@ describe("ProviderCommandReactor", () => {detail: "Provider instance 'missing' is not available.",unavailability: "temporary-failure",requestId: "user-message-missing-bot-engine",+ providerInstanceId: "missing",},}),);@@ -324,6 +325,50 @@ describe("ProviderCommandReactor", () => {expect(harness.sendTurn).not.toHaveBeenCalled();});+ it("keeps a missing sign-in typed so the chat can point to Settings", async () => {+ const harness = await createHarness({+ botEngine: { provider: "claudeAgent", model: "claude-sonnet-4-6" },+ unavailableEngine: "missing-login",+ });++ await harness.run(+ harness.engine.dispatch({+ type: "thread.turn.start",+ commandId: CommandId.make("cmd-turn-start-signed-out-bot-engine"),+ threadId: ThreadId.make("thread-1"),+ message: {+ messageId: asMessageId("user-message-signed-out-bot-engine"),+ role: "user",+ text: "use signed out engine",+ attachments: [],+ },+ interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,+ runtimeMode: "approval-required",+ createdAt: "2026-01-01T00:00:00.000Z",+ }),+ );++ await harness.waitFor(() => harness.resolveEngine.mock.calls.length === 1);+ await harness.drain();++ const thread = (await harness.readModel()).threads.find(+ (entry) => entry.id === ThreadId.make("thread-1"),+ );++ expect(thread?.activities).toContainEqual(+ expect.objectContaining({+ kind: "provider.turn.start.failed",+ payload: {+ detail: "Connect Claude in Settings.",+ unavailability: "missing-login",+ requestId: "user-message-signed-out-bot-engine",+ providerInstanceId: "claudeAgent",+ },+ }),+ );+ expect(harness.startSession).not.toHaveBeenCalled();+ });+it("reports a disabled engine as one readable line and names the bot on its bot work", async () => {const harness = await createHarness({botEngine: { provider: "codex", model: "gpt-5-codex" },diff --git a/apps/server/src/orchestration/Layers/provider-command/Failures.ts b/apps/server/src/orchestration/Layers/provider-command/Failures.tsindex 33cb90351..3736dbb9b 100644--- a/apps/server/src/orchestration/Layers/provider-command/Failures.ts+++ b/apps/server/src/orchestration/Layers/provider-command/Failures.ts@@ -16,11 +16,20 @@ import {isBotUsageCapExceeded,isComposioOperationError,isProviderAdapterRequestError,+ isUnsupportedEngineError,withoutUnavailability,} from "./Fields.ts";import type { createDependencies } from "./Dependencies.ts";import type { createContext } from "./Context.ts";+/** A failed provider command as the chat shows it. */+interface ProviderFailureReport {+ readonly detail: string;+ readonly unavailability: OrchestrationLatestTurn["unavailability"];+ /** The instance that failed, when an engine refusal named it. */+ readonly providerInstanceId?: string;+}+export function createFailures({agentController,projectionBotRepository,@@ -79,6 +88,8 @@ export function createFailures({readonly createdAt: string;readonly requestId?: string;readonly unavailability?: OrchestrationLatestTurn["unavailability"];+ /** The instance that failed, so the chat repairs it even after the bot switches models. */+ readonly providerInstanceId?: string | undefined;}) =>Effect.all({commandId: serverCommandId("provider-failure-activity"),@@ -98,6 +109,7 @@ export function createFailures({detail: input.detail,...(input.unavailability ? { unavailability: input.unavailability } : {}),...(input.requestId ? { requestId: input.requestId } : {}),+ ...(input.providerInstanceId ? { providerInstanceId: input.providerInstanceId } : {}),},turnId: input.turnId,createdAt: input.createdAt,@@ -202,19 +214,32 @@ export function createFailures({return readableErrorDetail(failReason ? failReason.error : Cause.squash(cause));};- const formatFailure = (cause: Cause.Cause<unknown>) => {+ const formatFailure = (cause: Cause.Cause<unknown>): ProviderFailureReport => {const detail = formatFailureDetail(cause);const failReason = cause.reasons.find(Cause.isFailReason);if (isBotUsageCapExceeded(failReason?.error)) {- return { detail, unavailability: "usage-cap" as const };+ return { detail, unavailability: "usage-cap" };+ }++ // An engine refusal names the instance that failed, so the chat can+ // repair that one even after the bot moves to another model.+ if (isUnsupportedEngineError(failReason?.error)) {+ const engineError = failReason.error;++ return {+ detail,+ unavailability:+ engineError.unavailability ?? providerUnavailabilityFromDetail("unknown", detail),+ providerInstanceId: engineError.provider,+ };}const provider = isProviderAdapterRequestError(failReason?.error)? failReason.error.provider: "unknown";- return { detail, unavailability: providerUnavailabilityFromDetail(provider, detail) } as const;+ return { detail, unavailability: providerUnavailabilityFromDetail(provider, detail) };};const setThreadSession = (input: {diff --git a/apps/server/src/orchestration/Layers/provider-command/Fields.ts b/apps/server/src/orchestration/Layers/provider-command/Fields.tsindex 43ddcacb7..6865faf46 100644--- a/apps/server/src/orchestration/Layers/provider-command/Fields.ts+++ b/apps/server/src/orchestration/Layers/provider-command/Fields.ts@@ -10,12 +10,17 @@ import { stripWorktreeBranchPrefix, WORKTREE_BRANCH_PREFIX } from "@akeru/sharedimport * as Cause from "effect/Cause";import * as Duration from "effect/Duration";import * as Schema from "effect/Schema";-import { ProviderAdapterRequestError } from "../../../provider/Errors.ts";+import {+ AgentControllerUnsupportedEngineError,+ ProviderAdapterRequestError,+} from "../../../provider/Errors.ts";import type { AgentControllerError } from "../../../provider/Errors.ts";import { BotUsageCapExceeded } from "../../../usage/BotUsageLedger.ts";export const isProviderAdapterRequestError = Schema.is(ProviderAdapterRequestError);+export const isUnsupportedEngineError = Schema.is(AgentControllerUnsupportedEngineError);+export const isBotUsageCapExceeded = Schema.is(BotUsageCapExceeded);export const isComposioOperationError = Schema.is(ComposioOperationError);diff --git a/apps/server/src/orchestration/Layers/provider-command/Turns.ts b/apps/server/src/orchestration/Layers/provider-command/Turns.tsindex 392bbfb7f..bfdb927bd 100644--- a/apps/server/src/orchestration/Layers/provider-command/Turns.ts+++ b/apps/server/src/orchestration/Layers/provider-command/Turns.ts@@ -130,7 +130,7 @@ export function createTurns({return Effect.void;}- const { detail, unavailability } = formatFailure(cause);+ const { detail, unavailability, providerInstanceId } = formatFailure(cause);// The failure activity lands before the session error clears the pending// turn start, so a restart either replays the turn start or finds the@@ -149,6 +149,7 @@ export function createTurns({createdAt: event.payload.createdAt,requestId: event.payload.messageId,unavailability,+ providerInstanceId,});yield* setThreadSessionErrorOnTurnStartFailure({threadId: event.payload.threadId,diff --git a/apps/server/src/orchestration/Layers/test-support/ProviderCommandMocks.ts b/apps/server/src/orchestration/Layers/test-support/ProviderCommandMocks.tsindex 20f50d8da..f424f5740 100644--- a/apps/server/src/orchestration/Layers/test-support/ProviderCommandMocks.ts+++ b/apps/server/src/orchestration/Layers/test-support/ProviderCommandMocks.ts@@ -61,7 +61,7 @@ export type ProviderCommandHarnessOptions = {};readonly botUsageCap?: { readonly unit: "tokens"; readonly limit: number } | null;readonly bindTurnFailure?: boolean;- readonly unavailableEngine?: boolean;+ readonly unavailableEngine?: boolean | "missing-login";readonly disabledEngine?: boolean;readonly composioResolveRuntimeMcpServer?: ComposioServiceShape["resolveRuntimeMcpServer"];readonly enableAgentBrowserAccess?: boolean;@@ -318,6 +318,17 @@ export function createProviderCommandMocks(vi.fn<AgentControllerShape["resolveEngine"]>(({ engine, fallback, mode }) => {notify();+ if (input?.unavailableEngine === "missing-login" && engine !== null) {+ return Effect.fail(+ new AgentControllerUnsupportedEngineError({+ provider: engine.provider,+ model: engine.model,+ detail: "Connect Claude in Settings.",+ unavailability: "missing-login",+ }),+ );+ }+if (input?.unavailableEngine === true && engine !== null) {return Effect.fail(new AgentControllerUnsupportedEngineError({diff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.tsindex ab6475dd8..18349471f 100644--- a/apps/server/src/provider/Errors.ts+++ b/apps/server/src/provider/Errors.ts@@ -1,4 +1,5 @@import * as Predicate from "effect/Predicate";+import { ServerProviderUnavailability } from "@akeru/contracts";import * as Schema from "effect/Schema";import type { CheckpointServiceError } from "../checkpointing/Errors.ts";@@ -196,6 +197,9 @@ export class AgentControllerUnsupportedEngineError extends Schema.TaggedErrorClaprovider: Schema.String,model: Schema.String,detail: Schema.String,+ // Set when the user can fix the failure, so the chat names the fix instead+ // of asking for feedback.+ unavailability: Schema.optional(ServerProviderUnavailability),cause: Schema.optional(Schema.Defect()),},) {diff --git a/apps/server/src/provider/Layers/AgentController.models.failures.test.ts b/apps/server/src/provider/Layers/AgentController.models.failures.test.tsindex 00b694561..ab2117207 100644--- a/apps/server/src/provider/Layers/AgentController.models.failures.test.ts+++ b/apps/server/src/provider/Layers/AgentController.models.failures.test.ts@@ -486,6 +486,8 @@ describe("AgentControllerLive", () => {if (Predicate.isTagged(failure, "AgentControllerUnsupportedEngineError")) {assert.include(failure.detail, "Model 'not-a-model' is not available for codex.");++ assert.equal(failure.unavailability, "unsupported-model");}expect(mastra.createSession).not.toHaveBeenCalled();diff --git a/apps/server/src/provider/Layers/AgentController.models.resume.test.ts b/apps/server/src/provider/Layers/AgentController.models.resume.test.tsindex 564599393..fc18caabd 100644--- a/apps/server/src/provider/Layers/AgentController.models.resume.test.ts+++ b/apps/server/src/provider/Layers/AgentController.models.resume.test.ts@@ -659,12 +659,11 @@ describe("AgentControllerLive", () => {assert.equal(error._tag, "AgentControllerUnsupportedEngineError");if (Predicate.isTagged(error, "AgentControllerUnsupportedEngineError")) {- assert.include(error.detail, `Provider instance '${provider}' is not available.`);+ // The chat shows the detail, so it carries the fix, not a generic refusal.+ assert.include(error.detail, expectedIssue);- const causeMessage =- error.cause instanceof Error ? error.cause.message : String(error.cause ?? "");-- assert.include(causeMessage, expectedIssue);+ // Signing in cannot fix a custom-credential instance.+ assert.isUndefined(error.unavailability);}expect(bridge.startSession).not.toHaveBeenCalled();@@ -676,6 +675,107 @@ describe("AgentControllerLive", () => {);},);++ it.effect("asks to sign in when a saved-account provider is not connected", () => {+ const bridge = makeBridge();+ const mastra = mastraHarnessFixture();++ const service: ProviderServiceShape = {+ ...bridge.service,+ getInstanceInfo: (candidate) =>+ Effect.succeed({+ instanceId: candidate,+ driverKind: ProviderDriverKind.make("claudeAgent"),+ displayName: undefined,+ enabled: true,+ continuationIdentity: {+ driverKind: ProviderDriverKind.make("claudeAgent"),+ continuationKey: `claudeAgent:instance:${candidate}`,+ },+ mastraConnection: {+ environment: {},+ instanceEnvironment: {},+ useSavedCredential: true,+ },+ }),+ };++ return provideController(+ Effect.gen(function* () {+ const controller = yield* AgentController;++ const error = yield* controller+ .resolveEngine({+ threadId: ThreadId.make("thread-claude-signed-out"),+ engine: { provider: "claudeAgent", model: "claude-sonnet-4-6" },+ fallback: codexSelection,+ mode: "default",+ botConversation: true,+ })+ .pipe(Effect.flip);++ assert.equal(error._tag, "AgentControllerUnsupportedEngineError");++ if (Predicate.isTagged(error, "AgentControllerUnsupportedEngineError")) {+ assert.include(error.detail, "Connect Claude in Settings.");+ assert.equal(error.unavailability, "missing-login");+ }+ }),+ service,+ mastra.factory,+ );+ });++ it.effect("does not ask to sign in to a provider that has no account", () => {+ const bridge = makeBridge();+ const mastra = mastraHarnessFixture();++ const service: ProviderServiceShape = {+ ...bridge.service,+ getInstanceInfo: (candidate) =>+ Effect.succeed({+ instanceId: candidate,+ driverKind: ProviderDriverKind.make("customOpenai"),+ displayName: undefined,+ enabled: true,+ continuationIdentity: {+ driverKind: ProviderDriverKind.make("customOpenai"),+ continuationKey: `customOpenai:instance:${candidate}`,+ },+ mastraConnection: {+ environment: {},+ instanceEnvironment: {},+ useSavedCredential: true,+ },+ }),+ };++ return provideController(+ Effect.gen(function* () {+ const controller = yield* AgentController;++ const error = yield* controller+ .resolveEngine({+ threadId: ThreadId.make("thread-custom-api-no-url"),+ engine: { provider: "customOpenai", model: "llama-3.3" },+ fallback: codexSelection,+ mode: "default",+ botConversation: true,+ })+ .pipe(Effect.flip);++ assert.equal(error._tag, "AgentControllerUnsupportedEngineError");++ if (Predicate.isTagged(error, "AgentControllerUnsupportedEngineError")) {+ assert.include(error.detail, "This Custom API instance needs a base URL.");++ assert.isUndefined(error.unavailability);+ }+ }),+ service,+ mastra.factory,+ );+ });});});diff --git a/apps/server/src/provider/Layers/agentController/EngineRouting.ts b/apps/server/src/provider/Layers/agentController/EngineRouting.tsindex ec743e58e..765d49f03 100644--- a/apps/server/src/provider/Layers/agentController/EngineRouting.ts+++ b/apps/server/src/provider/Layers/agentController/EngineRouting.ts@@ -57,7 +57,7 @@ export function createEngineRouting(deps: {new AgentControllerUnsupportedEngineError({provider,model,- detail: `Provider instance '${provider}' is not available.`,+ detail: `Provider instance '${provider}' is not set up.`,cause,});@@ -94,6 +94,7 @@ export function createEngineRouting(deps: {provider,model,detail: `Model '${model}' is not available for ${name}.`,+ unavailability: "unsupported-model",});}}@@ -115,7 +116,19 @@ export function createEngineRouting(deps: {: false,);- if (issue) return yield* unavailable(new Error(issue));+ if (issue) {+ return yield* new AgentControllerUnsupportedEngineError({+ provider,+ model,+ detail: issue,+ // Signing in only fixes an instance that uses a saved account. A+ // custom-credential instance, or a driver with no account such as+ // Custom API, keeps its own message.+ ...(subscriptionProvider && routing.mastraConnection?.useSavedCredential+ ? { unavailability: "missing-login" as const }+ : {}),+ });+ }}const capabilities = deps.usesMastraCode(routing.driverKind)diff --git a/apps/server/src/provider/Layers/agentController/ProviderAccess.ts b/apps/server/src/provider/Layers/agentController/ProviderAccess.tsindex 2a2bf820a..359cccf8d 100644--- a/apps/server/src/provider/Layers/agentController/ProviderAccess.ts+++ b/apps/server/src/provider/Layers/agentController/ProviderAccess.ts@@ -1,6 +1,7 @@import { harnessCredentialIssue } from "../../HarnessProviderStatus.ts";import { ProviderDriverKind } from "@akeru/contracts";import { ProviderInstanceId } from "@akeru/contracts";+import { PROVIDER_ACCOUNT_NAMES } from "@akeru/contracts";import * as NodeCrypto from "node:crypto";import * as Path from "effect/Path";import * as Effect from "effect/Effect";@@ -114,7 +115,7 @@ export function mastraConnectionIssue(return savedCredentialConnected? undefined- : `Connect ${provider} in Settings before starting.`;+ : `Connect ${PROVIDER_ACCOUNT_NAMES[provider] ?? provider} in Settings.`;}switch (String(provider)) {diff --git a/apps/web/src/components/SurfaceNavigationCoordinator.tsx b/apps/web/src/components/SurfaceNavigationCoordinator.tsxindex 3e4ed8a00..d1bbad693 100644--- a/apps/web/src/components/SurfaceNavigationCoordinator.tsx+++ b/apps/web/src/components/SurfaceNavigationCoordinator.tsx@@ -9,6 +9,7 @@ import {} from "../settingsDialogStore";import { closeUsage, useUsageDialogStore } from "../usageDialogStore";import { channelProviderFromSettingsTarget } from "./settings/channelProviderMeta";+import { providerCatalogSlugFromSettingsTarget } from "./settings/providerCatalog";/** Bridges legacy imperative open helpers to the routed workspace surfaces. */export function SurfaceNavigationCoordinator() {@@ -21,17 +22,24 @@ export function SurfaceNavigationCoordinator() {useEffect(() => {if (settingsSection !== null) {- // A channel target, such as a repair link, opens that provider's own page.+ // A channel or provider target, such as a repair link, opens that provider's own page.const channel =settingsSection === "channels" ? channelProviderFromSettingsTarget(settingsTarget) : null;+ const providerId =+ settingsSection === "providers"+ ? providerCatalogSlugFromSettingsTarget(settingsTarget)+ : null;+void (channel? navigate({ to: "/settings/channels/$channel", params: { channel } })- : navigate({- to: "/settings/$section",- params: { section: settingsSection },- hash: settingsTarget ?? "",- }));+ : providerId+ ? navigate({ to: "/settings/providers/$providerId", params: { providerId } })+ : navigate({+ to: "/settings/$section",+ params: { section: settingsSection },+ hash: settingsTarget ?? "",+ }));acknowledgeSettingsNavigation();return;diff --git a/apps/web/src/components/chat/ProviderUnavailableNotice.tsx b/apps/web/src/components/chat/ProviderUnavailableNotice.tsxindex e0ad4eadc..2c560d89b 100644--- a/apps/web/src/components/chat/ProviderUnavailableNotice.tsx+++ b/apps/web/src/components/chat/ProviderUnavailableNotice.tsx@@ -1,69 +1,83 @@import type { EnvironmentId } from "@akeru/contracts";import {joinProviderUnavailability,+ providerReasonNeedsSignIn,type ProviderAvailabilityPresentation,} from "@akeru/client-runtime/provider-availability";-import { settingsDeepLinkHref } from "@akeru/client-runtime/settings-deep-link";-import { CircleAlertIcon } from "lucide-react";+import { CircleAlertIcon, Settings2Icon } from "lucide-react";import { useI18n } from "../../i18n";import { cn } from "../../lib/utils";import { openSettings } from "../../settingsDialogStore";-import { parseSettingsDeepLink } from "../../settingsDeepLink";+import { providerCatalogTargetId, type ProviderCatalogEntry } from "../settings/providerCatalog";+import { SettingsEntityIcon } from "../settings/settingsDetailLayout";import { Button } from "../ui/button";-import { SettingsLinkChip } from "./SettingsLinkChip";-const PROVIDERS_HREF = settingsDeepLinkHref("providers");--const PROVIDERS_DESTINATION = parseSettingsDeepLink(PROVIDERS_HREF);--/** The Settings > Providers chip shown wherever reconnecting a provider fixes a failure. */-export function ProviderSettingsChip({- environmentId,- className,-}: {- readonly environmentId: EnvironmentId | null;- readonly className?: string;-}) {- const { t } = useI18n();+/** "Connect Claude" when signing in fixes it, else a plain way into Claude's settings. */+function providerButtonLabel(+ t: ReturnType<typeof useI18n>["t"],+ provider: ProviderCatalogEntry,+ reason: ProviderAvailabilityPresentation["reason"],+) {+ return providerReasonNeedsSignIn(reason)+ ? t("Connect {provider}", { provider: provider.label })+ : t("Open {provider} settings", { provider: provider.label });+}- if (!PROVIDERS_DESTINATION) return null;+/** Opens the provider's own settings page, or the Providers list when there is none. */+function openProviderSettings(+ provider: ProviderCatalogEntry | null | undefined,+ environmentId: EnvironmentId | null,+) {+ openSettings("providers", provider ? providerCatalogTargetId(provider) : null, environmentId);+}+/** The provider's logo in a small tile, so a failure card says which account it means. */+export function ProviderLogoTile({ provider }: { readonly provider: ProviderCatalogEntry }) {return (- <SettingsLinkChip- href={PROVIDERS_HREF}- destination={PROVIDERS_DESTINATION}- environmentId={environmentId}- {...(className ? { className } : {})}- >- {t("Settings > Providers")}- </SettingsLinkChip>+ <span className="flex size-8 shrink-0 items-center justify-center rounded-lg border border-border/70 bg-background">+ <SettingsEntityIcon icon={provider.icon} />+ </span>);}/**- * The next step for a provider failure: the Providers chip, or a button into- * this bot's usage settings when an Akeru cap blocked the turn. Renders nothing- * when waiting or picking another model is the only step.+ * The next step for a provider failure: a button into that provider's+ * settings, or into this bot's usage settings when an Akeru cap blocked the+ * turn. Renders nothing when waiting or picking another model is the only step.*/export function ProviderRepairAction({action,+ reason,+ provider,environmentId,onOpenUsage,}: {readonly action: ProviderAvailabilityPresentation["action"];+ readonly reason?: ProviderAvailabilityPresentation["reason"];+ readonly provider?: ProviderCatalogEntry | null | undefined;readonly environmentId: EnvironmentId | null;readonly onOpenUsage?: (() => void) | undefined;}) {const { t } = useI18n();if (action === "providers") {- return <ProviderSettingsChip environmentId={environmentId} />;+ return (+ <Button+ size="sm"+ type="button"+ variant={provider ? "default" : "outline"}+ onClick={() => openProviderSettings(provider, environmentId)}+ >+ {provider ? null : <Settings2Icon aria-hidden="true" />}+ {provider ? providerButtonLabel(t, provider, reason) : t("Open Providers")}+ </Button>+ );}if (action === "usage" && onOpenUsage) {return (- <Button size="xs" type="button" variant="outline" onClick={onOpenUsage}>+ <Button size="sm" type="button" variant="outline" onClick={onOpenUsage}>{t("Bot settings")}</Button>);@@ -79,13 +93,19 @@ export function ProviderRepairAction({*/export function ProviderUnavailableNotice({presentation,+ provider,environmentId,onOpenUsage,className,id,}: {readonly id?: string | undefined;- readonly presentation: Pick<ProviderAvailabilityPresentation, "title" | "description" | "action">;+ readonly presentation: Pick<+ ProviderAvailabilityPresentation,+ "title" | "description" | "action" | "reason"+ >;+ /** The provider whose settings fix this, when the bot's engine names one. */+ readonly provider?: ProviderCatalogEntry | null | undefined;readonly environmentId: EnvironmentId | null;readonly onOpenUsage?: (() => void) | undefined;readonly className?: string;@@ -100,7 +120,11 @@ export function ProviderUnavailableNotice({role="status"data-provider-unavailable="">- <CircleAlertIcon aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-warning" />+ {provider ? (+ <ProviderLogoTile provider={provider} />+ ) : (+ <CircleAlertIcon aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-warning" />+ )}<div className="min-w-0 flex-1"><p className="text-sm font-medium leading-5">{presentation.title}</p><p className="mt-0.5 text-xs leading-4.5 text-muted-foreground">@@ -110,6 +134,8 @@ export function ProviderUnavailableNotice({<div className="mt-2 flex flex-wrap items-center gap-1.5"><ProviderRepairActionaction={presentation.action}+ reason={presentation.reason}+ provider={provider}environmentId={environmentId}onOpenUsage={onOpenUsage}/>@@ -127,12 +153,18 @@ export function ProviderUnavailableNotice({*/export function ProviderUnavailableLine({presentation,+ provider,environmentId,onOpenUsage,id,}: {readonly id?: string | undefined;- readonly presentation: Pick<ProviderAvailabilityPresentation, "title" | "description" | "action">;+ readonly presentation: Pick<+ ProviderAvailabilityPresentation,+ "title" | "description" | "action" | "reason"+ >;+ /** The provider whose settings fix this, when the bot's engine names one. */+ readonly provider?: ProviderCatalogEntry | null | undefined;readonly environmentId: EnvironmentId | null;readonly onOpenUsage?: (() => void) | undefined;}) {@@ -144,9 +176,10 @@ export function ProviderUnavailableLine({size="xs"type="button"variant="outline"- onClick={() => openSettings("providers", null, environmentId)}+ onClick={() => openProviderSettings(provider, environmentId)}>- {t("Set up a provider")}+ {provider ? <SettingsEntityIcon icon={provider.icon} className="size-3.5" /> : null}+ {provider ? providerButtonLabel(t, provider, presentation.reason) : t("Set up a provider")}</Button>) : presentation.action === "usage" && onOpenUsage ? (<Button size="xs" type="button" variant="outline" onClick={onOpenUsage}>diff --git a/apps/web/src/components/chat/ThreadErrorBanner.test.tsx b/apps/web/src/components/chat/ThreadErrorBanner.test.tsxindex e08d6d47e..3382bab51 100644--- a/apps/web/src/components/chat/ThreadErrorBanner.test.tsx+++ b/apps/web/src/components/chat/ThreadErrorBanner.test.tsx@@ -1,6 +1,7 @@import { renderToStaticMarkup } from "react-dom/server";import { presentThreadError } from "@akeru/client-runtime/errors";import { describe, expect, it } from "vite-plus/test";+import { providerCatalogEntry } from "../settings/providerCatalog";import {dismissThreadErrorBannerForSession,@@ -131,21 +132,34 @@ describe("ThreadErrorBanner", () => {"ProviderValidationError: Provider validation failed in AgentController.inspectEngine: Provider instance 'codex' is disabled in Akeru Bot settings. at DisabledProviderError (file:///home/leo/app.ts:1:2)";expect(presentThreadError(error)).toEqual({- title: "Codex is turned off",- description: "Turn Codex on in Settings > Providers, then send your message again.",+ title: "ChatGPT is turned off",+ description: "Turn ChatGPT on in Settings > Providers, then send your message again.",technicalDetails: "Provider instance “codex” is disabled.",action: "providers",+ reason: "disabled",});const markup = renderToStaticMarkup(<ThreadErrorBanner error={error} threadKey="env:thread-disabled-provider" />,);- expect(markup).toContain("Codex is turned off");- expect(markup).toContain('href="grokbot://app/v1/settings?id=providers"');+ expect(markup).toContain("ChatGPT is turned off");+ expect(markup).toContain(">Open Providers<");expect(markup).not.toContain("Send feedback");expect(markup).not.toContain("AgentController.inspectEngine");expect(markup).not.toContain("/home/leo");++ // Signing in won't turn a provider on, so its button just opens the page.+ const withLogo = renderToStaticMarkup(+ <ThreadErrorBanner+ error={error}+ threadKey="env:thread-disabled-provider-logo"+ context={{ provider: providerCatalogEntry("chatgpt") ?? null }}+ />,+ );++ expect(withLogo).toContain(">Open ChatGPT settings<");+ expect(withLogo).not.toContain("Connect ChatGPT");});it("uses the server's failure category to name the provider and the fix", () => {@@ -159,7 +173,24 @@ describe("ThreadErrorBanner", () => {expect(markup).toContain("Claude sign-in expired");expect(markup).toContain("Reconnect Claude in Settings > Providers");- expect(markup).toContain('href="grokbot://app/v1/settings?id=providers"');+ expect(markup).toContain(">Open Providers<");expect(markup).not.toContain("Send feedback");});++ it("shows the provider's logo and a button straight to its page", () => {+ const claude = providerCatalogEntry("claude")!;++ const markup = renderToStaticMarkup(+ <ThreadErrorBanner+ error="Connect Claude in Settings."+ threadKey="env:thread-signed-out"+ context={{ unavailability: "missing-login", providerName: "Claude", provider: claude }}+ />,+ );++ expect(markup).toContain("Claude is not connected");+ expect(markup).toContain(">Connect Claude<");+ expect(markup).toContain("<svg");+ expect(markup).not.toContain("Open Providers");+ });});diff --git a/apps/web/src/components/chat/ThreadErrorBanner.tsx b/apps/web/src/components/chat/ThreadErrorBanner.tsxindex 3b4f6423e..abb0725d2 100644--- a/apps/web/src/components/chat/ThreadErrorBanner.tsx+++ b/apps/web/src/components/chat/ThreadErrorBanner.tsx@@ -7,7 +7,8 @@ import type { EnvironmentId } from "@akeru/contracts";import { useI18n } from "../../i18n";import { openProductFeedbackWithPrefill } from "../../productFeedbackStore";import { Button } from "../ui/button";-import { ProviderRepairAction } from "./ProviderUnavailableNotice";+import type { ProviderCatalogEntry } from "../settings/providerCatalog";+import { ProviderLogoTile, ProviderRepairAction } from "./ProviderUnavailableNotice";export function threadErrorFeedbackDraft(error: string): string {const presentation = presentThreadError(error);@@ -51,8 +52,8 @@ export const ThreadErrorBanner = memo(function ThreadErrorBanner({}: {error: string | null;threadKey: string;- /** The failure's category and names, when the server reported them. */- context?: ThreadErrorContext;+ /** The failure's category and names, plus the provider page that fixes it. */+ context?: ThreadErrorContext & { readonly provider?: ProviderCatalogEntry | null };environmentId?: EnvironmentId | null;onOpenUsage?: () => void;onDismiss?: () => void;@@ -73,6 +74,8 @@ export const ThreadErrorBanner = memo(function ThreadErrorBanner({const presentation = presentThreadError(error, context, t);+ const provider = presentation.action === "providers" ? (context?.provider ?? null) : null;+const dismiss = () => {dismissThreadErrorBannerForSession(bannerKey);setLocallyDismissedKey(bannerKey);@@ -99,27 +102,36 @@ export const ThreadErrorBanner = memo(function ThreadErrorBanner({</Button><div className="flex min-w-0 items-start gap-2.5">- <CircleAlertIcon aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-destructive" />+ {provider ? (+ <ProviderLogoTile provider={provider} />+ ) : (+ <CircleAlertIcon+ aria-hidden="true"+ className="mt-0.5 size-4 shrink-0 text-destructive"+ />+ )}<div className="min-w-0 flex-1"><p className="text-sm font-medium leading-5">{presentation.title}</p><p className="mt-0.5 text-xs leading-4.5 text-muted-foreground">{presentation.description}</p>- <div className="mt-2 flex flex-wrap items-center gap-1.5">+ <div className="mt-2.5 flex flex-wrap items-center gap-2">{onResume ? (- <Button size="xs" type="button" onClick={onResume} disabled={resuming}>+ <Button size="sm" type="button" onClick={onResume} disabled={resuming}>{resuming ? t("Resuming…") : t("Resume")}</Button>) : null}<ProviderRepairActionaction={presentation.action}+ reason={presentation.reason}+ provider={provider}environmentId={environmentId}onOpenUsage={onOpenUsage}/>{presentation.action === "feedback" ? (<Button- size="xs"+ size="sm"type="button"variant="outline"onClick={() => openProductFeedbackWithPrefill(threadErrorFeedbackDraft(error))}diff --git a/apps/web/src/components/roster/BotEngineFields.tsx b/apps/web/src/components/roster/BotEngineFields.tsxindex 1eafb3ff0..14b129337 100644--- a/apps/web/src/components/roster/BotEngineFields.tsx+++ b/apps/web/src/components/roster/BotEngineFields.tsx@@ -45,6 +45,7 @@ export function BotEngineFields({<ProviderUnavailableNoticeclassName="mt-3 mb-2.5 max-w-2xl"presentation={draft.engineUnavailability}+ provider={draft.engineUnavailability.provider}environmentId={environmentId}/>) : null}diff --git a/apps/web/src/components/roster/BotThreadLanding.tsx b/apps/web/src/components/roster/BotThreadLanding.tsxindex 00c086198..cbbabf844 100644--- a/apps/web/src/components/roster/BotThreadLanding.tsx+++ b/apps/web/src/components/roster/BotThreadLanding.tsx@@ -131,6 +131,7 @@ export function BotThreadLanding({stickyEngine,instanceEntries,runtime.failure?.unavailability,+ runtime.failure?.providerInstanceId,);const openBotSettings = () => void navigate({ to: "/bots/$botId/settings", params: { botId } });@@ -611,6 +612,7 @@ export function BotThreadLanding({/>{sendBlocked && engineUnavailability ? (<ProviderUnavailableLine+ provider={engineUnavailability.provider}id={engineNoticeId}presentation={engineUnavailability}environmentId={environmentId}diff --git a/apps/web/src/components/roster/GroupThreadLanding.tsx b/apps/web/src/components/roster/GroupThreadLanding.tsxindex 577a12b22..367d96b0e 100644--- a/apps/web/src/components/roster/GroupThreadLanding.tsx+++ b/apps/web/src/components/roster/GroupThreadLanding.tsx@@ -124,6 +124,7 @@ export function GroupThreadLanding({ groupId }: { readonly groupId: string }) {respondingEngine.selection,respondingEngine.instanceEntries,runtime.failure?.unavailability,+ runtime.failure?.providerInstanceId,);const members = groupdiff --git a/apps/web/src/components/roster/NewBotDialog.tsx b/apps/web/src/components/roster/NewBotDialog.tsxindex f5a60e7b9..1430841ff 100644--- a/apps/web/src/components/roster/NewBotDialog.tsx+++ b/apps/web/src/components/roster/NewBotDialog.tsx@@ -90,6 +90,7 @@ export function NewBotDialog({<div className="sm:col-span-2"><ProviderUnavailableNoticepresentation={defaultEngine.unavailability}+ provider={defaultEngine.unavailability.provider}environmentId={environmentId}/></div>diff --git a/apps/web/src/components/roster/botEngineSelection.test.ts b/apps/web/src/components/roster/botEngineSelection.test.tsindex d94ef7ddc..08b713b30 100644--- a/apps/web/src/components/roster/botEngineSelection.test.ts+++ b/apps/web/src/components/roster/botEngineSelection.test.ts@@ -5,6 +5,7 @@ import { describe, expect, it } from "vite-plus/test";import { deriveProviderInstanceEntries } from "../../providerInstances";import { makeComposerTestProvider } from "../../test/composerTestProvider";+import { providerCatalogEntry } from "../settings/providerCatalog";import {botEngineFailureContext,botEngineTakesDelegatedWork,@@ -86,14 +87,14 @@ describe("resolveStickyBotEngine", () => {expect(botEngineUnavailability({ instanceId, model: "gpt-5-codex" }, signedOut)).toMatchObject({reason: "expired-login",- title: "Codex sign-in expired",- description: "Reconnect Codex in Settings > Providers, then send your message again.",+ title: "ChatGPT sign-in expired",+ description: "Reconnect ChatGPT in Settings > Providers, then send your message again.",});expect(botEngineUnavailability({ instanceId, model: "gpt-5-codex" }, signedOut, zh),).toMatchObject({- title: "Codex 登录已过期",- description: "请在“设置 > 提供商”中重新连接 Codex,然后重新发送消息。",+ title: "ChatGPT 登录已过期",+ description: "请在“设置 > 提供商”中重新连接 ChatGPT,然后重新发送消息。",});expect(botEngineUnavailability({ instanceId, model: "gpt-4-retired" }, signedIn)).toMatchObject({@@ -263,15 +264,72 @@ describe("botEngineFailureContext", () => {),).toEqual({unavailability: "missing-login",- providerName: entry.displayName,+ providerName: "ChatGPT",+ provider: providerCatalogEntry("chatgpt"),modelName: model.name,});expect(botEngineFailureContext(null, instanceEntries, undefined)).toEqual({unavailability: null,providerName: null,+ provider: null,modelName: null,});});++ it("keeps naming the provider that failed after the bot switches models", () => {+ const instanceEntries = deriveProviderInstanceEntries([makeComposerTestProvider()]);+ const entry = instanceEntries[0]!;++ expect(+ botEngineFailureContext(+ { instanceId: entry.instanceId, model: entry.models[0]!.slug },+ instanceEntries,+ "missing-login",+ "claudeAgent",+ ),+ ).toEqual({+ unavailability: "missing-login",+ providerName: "Claude",+ provider: providerCatalogEntry("claude"),+ modelName: null,+ });+ });++ it("keeps a name the user gave the built-in instance", () => {+ const instanceEntries = deriveProviderInstanceEntries([+ { ...makeComposerTestProvider(), displayName: "Work Codex" },+ ]);++ const entry = instanceEntries[0]!;++ expect(+ botEngineFailureContext(+ { instanceId: entry.instanceId, model: entry.models[0]!.slug },+ instanceEntries,+ "missing-login",+ ),+ ).toMatchObject({ providerName: "Work Codex", provider: providerCatalogEntry("chatgpt") });+ });++ it("keeps a custom instance's own name and has no single provider page for it", () => {+ const instanceEntries = deriveProviderInstanceEntries([+ {+ ...makeComposerTestProvider(),+ instanceId: ProviderInstanceId.make("codex_work"),+ displayName: "Work Codex",+ },+ ]);++ const entry = instanceEntries[0]!;++ expect(+ botEngineFailureContext(+ { instanceId: entry.instanceId, model: entry.models[0]!.slug },+ instanceEntries,+ "missing-login",+ ),+ ).toMatchObject({ providerName: "Work Codex", provider: null });+ });});describe("botEngineTakesDelegatedWork", () => {diff --git a/apps/web/src/components/roster/botEngineSelection.ts b/apps/web/src/components/roster/botEngineSelection.tsindex de63aab2c..f31d4042b 100644--- a/apps/web/src/components/roster/botEngineSelection.ts+++ b/apps/web/src/components/roster/botEngineSelection.ts@@ -1,4 +1,5 @@import {+ stockProviderAccountName,ProviderDriverKind,ProviderInstanceId,type BotEngine,@@ -15,6 +16,7 @@ import type { ProviderAvailabilityTranslate } from "@akeru/client-runtime/providimport { resolveAppModelSelectionForInstance } from "../../modelSelection";import type { ComposerProviderCatalog } from "../chat/composerProviderMenuItems";import { formatProviderDriverKindLabel } from "../../providerModels";+import { providerCatalogEntryForDriver } from "../settings/providerCatalog";import {providerInstanceUnavailability,resolveSelectableProviderInstanceEntry,@@ -119,8 +121,37 @@ export function resolveStickyBotEngine(input: {const englishTranslate: ProviderAvailabilityTranslate = createTranslator("en").t;/**- * Why the bot's engine cannot run a turn right now, or null when it can. Feeds- * the disabled Send button and the quiet line below the composer.+ * What setup and failure copy calls a bot's provider: the account for a+ * built-in instance ("ChatGPT", not "Codex"), else the name the user gave it.+ */+function botProviderName(+ instanceId: ProviderInstanceId,+ entry: ProviderInstanceEntry | undefined,+): string {+ if (entry && !entry.isDefault) return entry.displayName;+ const driver = entry?.driverKind ?? ProviderDriverKind.make(instanceId);++ return (+ stockProviderAccountName(driver, entry?.displayName) ??+ entry?.displayName ??+ formatProviderDriverKindLabel(driver)+ );+}++/** The Providers page that can repair a bot's engine. Custom instances have none of their own. */+function botProviderCatalogEntry(+ instanceId: ProviderInstanceId,+ entry: ProviderInstanceEntry | undefined,+) {+ if (entry && !entry.isDefault) return null;++ return providerCatalogEntryForDriver(entry?.driverKind ?? instanceId) ?? null;+}++/**+ * Why the bot's engine cannot run a turn right now, or null when it can, with+ * the Providers page that fixes it. Feeds the disabled Send button and the+ * quiet line below the composer.*/export function botEngineUnavailability(selection: ModelSelection | null,@@ -134,6 +165,7 @@ export function botEngineUnavailability(description: t("Connect a provider in Settings > Providers so this bot can reply."),technicalDetails: "",action: "providers" as const,+ provider: null,};}@@ -142,36 +174,43 @@ export function botEngineUnavailability(const modelName =entry?.models.find((candidate) => candidate.slug === selection.model)?.name ?? selection.model;- return providerInstanceUnavailability(entry, {+ const unavailability = providerInstanceUnavailability(entry, {model: selection.model,modelName,- providerName: formatProviderDriverKindLabel(ProviderDriverKind.make(selection.instanceId)),+ providerName: botProviderName(selection.instanceId, entry),t,});++ return unavailability+ ? { ...unavailability, provider: botProviderCatalogEntry(selection.instanceId, entry) }+ : null;}/**- * What a chat's failure copy needs to name the provider and model that failed.- * Pass the result to `presentThreadError` or `ThreadErrorBanner`.+ * What a chat's failure copy needs to name the provider and model that failed,+ * plus the Providers page that fixes it. A failure that recorded its instance+ * keeps naming that one after the bot moves to another model. Pass the result+ * to `presentThreadError` or `ThreadErrorBanner`.*/export function botEngineFailureContext(selection: ModelSelection | null,instanceEntries: ReadonlyArray<ProviderInstanceEntry>,unavailability: ServerProviderUnavailability | null | undefined,+ failedInstanceId?: string | null,) {- const entry = instanceEntries.find((candidate) => candidate.instanceId === selection?.instanceId);+ const instanceId = failedInstanceId+ ? ProviderInstanceId.make(failedInstanceId)+ : (selection?.instanceId ?? null);++ // The bot's current model only describes the failure when it ran on the same instance.+ const model = selection?.instanceId === instanceId ? selection.model : null;+ const entry = instanceEntries.find((candidate) => candidate.instanceId === instanceId);return {unavailability: unavailability ?? null,- providerName:- entry?.displayName ??- (selection- ? formatProviderDriverKindLabel(ProviderDriverKind.make(selection.instanceId))- : null),- modelName:- entry?.models.find((model) => model.slug === selection?.model)?.name ??- selection?.model ??- null,+ providerName: instanceId ? botProviderName(instanceId, entry) : null,+ provider: instanceId ? botProviderCatalogEntry(instanceId, entry) : null,+ modelName: entry?.models.find((candidate) => candidate.slug === model)?.name ?? model ?? null,};}diff --git a/apps/web/src/components/roster/threadRuntimeWarning.logic.ts b/apps/web/src/components/roster/threadRuntimeWarning.logic.tsindex 8f859f56b..b8b4b5fc1 100644--- a/apps/web/src/components/roster/threadRuntimeWarning.logic.ts+++ b/apps/web/src/components/roster/threadRuntimeWarning.logic.ts@@ -87,6 +87,8 @@ export function latestThreadRuntimeError(export interface BotThreadFailure {readonly message: string;readonly unavailability: ServerProviderUnavailability | null;+ /** The provider instance that failed, so its repair survives a model change. */+ readonly providerInstanceId?: string;}/** A failed command, keeping the category the server attached to a provider failure. */@@ -136,13 +138,13 @@ export function latestBotThreadFailure(input: {if (!message) return null;+ const failure = latestTurnFailure(activities, latestTurn.requestedAt);+return {message,unavailability:- latestTurn.unavailability ??- session?.unavailability ??- latestTurnFailure(activities, latestTurn.requestedAt)?.unavailability ??- null,+ latestTurn.unavailability ?? session?.unavailability ?? failure?.unavailability ?? null,+ ...(failure?.providerInstanceId ? { providerInstanceId: failure.providerInstanceId } : {}),};}@@ -159,5 +161,6 @@ export function latestBotThreadFailure(input: {return {message,unavailability: failure?.unavailability ?? session.unavailability ?? null,+ ...(failure?.providerInstanceId ? { providerInstanceId: failure.providerInstanceId } : {}),};}diff --git a/apps/web/src/components/settings/providerCatalog.ts b/apps/web/src/components/settings/providerCatalog.tsindex eb87ff035..0eb055b0b 100644--- a/apps/web/src/components/settings/providerCatalog.ts+++ b/apps/web/src/components/settings/providerCatalog.ts@@ -3,6 +3,7 @@ import { ProviderDriverKind } from "@akeru/contracts";import { CustomApiIcon, type Icon } from "../Icons";import {SUBSCRIPTION_PROVIDERS,+ subscriptionProviderTargetId,type SubscriptionProviderDefinition,} from "./subscriptionProviders";@@ -60,3 +61,24 @@ export const PROVIDER_CATALOG: ReadonlyArray<ProviderCatalogEntry> = [export function providerCatalogEntry(slug: string): ProviderCatalogEntry | undefined {return PROVIDER_CATALOG.find((entry) => entry.slug === slug);}++/** The entry a built-in driver signs in through, e.g. Claude for `claudeAgent`. */+export function providerCatalogEntryForDriver(+ driver: string | null | undefined,+): ProviderCatalogEntry | undefined {+ return driver+ ? PROVIDER_CATALOG.find((entry) => entry.drivers.some((candidate) => candidate === driver))+ : undefined;+}++/** The Settings target that opens an entry's own page, used by repair buttons. */+export function providerCatalogTargetId(entry: ProviderCatalogEntry): string {+ return entry.account ? subscriptionProviderTargetId(entry.account.id) : `provider-${entry.slug}`;+}++/** The provider page a Settings target opens, so a repair link lands on that provider. */+export function providerCatalogSlugFromSettingsTarget(target: string | null): string | null {+ if (!target) return null;++ return PROVIDER_CATALOG.find((entry) => providerCatalogTargetId(entry) === target)?.slug ?? null;+}diff --git a/apps/web/src/providers/instanceAvailability.ts b/apps/web/src/providers/instanceAvailability.tsindex 9b318a774..4b99db870 100644--- a/apps/web/src/providers/instanceAvailability.ts+++ b/apps/web/src/providers/instanceAvailability.ts@@ -76,18 +76,15 @@ export function providerInstanceUnavailability(if (!reason) return null;- return {- reason,- ...presentProviderUnavailability(- {- reason,- providerName: entry?.displayName ?? options.providerName,- modelName: options.modelName ?? options.model,- detail: entry?.snapshot.unavailabilityDetail ?? entry?.snapshot.message,- },- options.t,- ),- };+ return presentProviderUnavailability(+ {+ reason,+ providerName: options.providerName ?? entry?.displayName,+ modelName: options.modelName ?? options.model,+ detail: entry?.snapshot.unavailabilityDetail ?? entry?.snapshot.message,+ },+ options.t,+ );}/** `providerInstanceUnavailability` as one sentence for a disabled row or button. */diff --git a/docs/user/provider-access.md b/docs/user/provider-access.mdindex e589f2dcb..0e9ce384b 100644--- a/docs/user/provider-access.md+++ b/docs/user/provider-access.md@@ -49,3 +49,5 @@ On desktop and web, each provider row shows its state and next step. Choose **AcOn mobile, open **Settings > Provider connections**. Each provider shows the same state and next step, and **Access details** shows the rest.Connections belong to one environment. A provider that is ready on one Akeru server can still be missing on another.++If you message a bot whose provider isn't connected, the chat says so and links to the provider settings. Connect the provider there, then send the message again.diff --git a/packages/client-runtime/src/errors/threadErrorPresentation.test.ts b/packages/client-runtime/src/errors/threadErrorPresentation.test.tsindex ef5c6d5eb..26f5e7c4d 100644--- a/packages/client-runtime/src/errors/threadErrorPresentation.test.ts+++ b/packages/client-runtime/src/errors/threadErrorPresentation.test.ts@@ -35,6 +35,54 @@ describe("presentThreadError", () => {});});+ it("sends a missing sign-in to Settings instead of asking for feedback", () => {+ expect(+ presentThreadError("Connect Claude in Settings.", { providerName: "Claude" }),+ ).toMatchObject({+ title: "Claude is not connected",+ action: "providers",+ });+ });++ it("treats an older server's unavailable instance as not set up", () => {+ // Older servers sent this for a missing sign-in and for a deleted instance alike.+ expect(presentThreadError("Provider instance 'claudeAgent' is not available.")).toMatchObject({+ title: "Claude is not set up",+ action: "providers",+ reason: "missing-provider",+ });+ });++ it("names the credential a custom instance is missing instead of asking for feedback", () => {+ expect(+ presentThreadError("This Codex instance needs OPENAI_API_KEY for the Akeru harness.", {+ providerName: "Work Codex",+ }),+ ).toMatchObject({+ title: "Work Codex needs OPENAI_API_KEY",+ action: "providers",+ });+ expect(+ presentThreadError(+ "ProviderError: This Custom API instance needs a base URL. at inspectEngine (file:///x.ts:1:2)",+ { providerName: "Custom API" },+ ),+ ).toMatchObject({ title: "Custom API needs a base URL", action: "providers" });+ expect(+ presentThreadError("Custom Kimi credentials are not supported by the Akeru harness."),+ ).toMatchObject({+ title: "The provider can't use custom credentials",+ action: "providers",+ });+ });++ it("names a provider instance that is not set up", () => {+ expect(presentThreadError("Provider instance 'claudeAgent' is not set up.")).toMatchObject({+ title: "Claude is not set up",+ action: "providers",+ });+ });+it("names the fix for a dropped connection instead of asking for feedback", () => {expect(presentThreadError("WebSocket disconnected")).toMatchObject({title: "Connection interrupted",diff --git a/packages/client-runtime/src/errors/threadErrorPresentation.ts b/packages/client-runtime/src/errors/threadErrorPresentation.tsindex 890f8738e..ba64f8299 100644--- a/packages/client-runtime/src/errors/threadErrorPresentation.ts+++ b/packages/client-runtime/src/errors/threadErrorPresentation.ts@@ -1,5 +1,5 @@import {- PROVIDER_DISPLAY_NAMES,+ PROVIDER_ACCOUNT_NAMES,isProviderDriverKind,type ServerProviderUnavailability,} from "@akeru/contracts";@@ -27,9 +27,10 @@ export interface ThreadErrorContext {}function providerName(id: string): string {- const provider = id.toLowerCase();+ // A legacy message may name the driver in any case, such as "Codex".+ const driver = isProviderDriverKind(id) ? id : id.toLowerCase();- return isProviderDriverKind(provider) ? (PROVIDER_DISPLAY_NAMES[provider] ?? id) : id;+ return isProviderDriverKind(driver) ? (PROVIDER_ACCOUNT_NAMES[driver] ?? id) : id;}function boundedTechnicalDetails(error: string): string {@@ -78,6 +79,16 @@ export function presentThreadError();}+ // Older servers said "is not available" for both a missing sign-in and a+ // deleted instance; "not set up" fits either.+ const missingProvider = error.match(+ /Provider instance ['"]([^'"]+)['"] is not (?:set up|available)/i,+ );++ if (missingProvider?.[1]) {+ return present("missing-provider", context.providerName ?? providerName(missingProvider[1]));+ }+if (/Bot '[^']+' is archived/.test(error)) {return {title: t("This bot is archived"),@@ -91,10 +102,50 @@ export function presentThreadError(return present("limit-reached");}- if (/not authenticated|authentication required|unauthorized|invalid api key/i.test(error)) {+ if (+ /not authenticated|authentication required|unauthorized|invalid api key|^Connect .+ in Settings/i.test(+ error,+ )+ ) {return present("missing-login");}+ // A provider set up with its own credentials: signing in to an account+ // won't fix it, so name what the instance is missing.+ const provider = context.providerName;++ const missingCredential = error.match(+ /This .+? instance needs (.+?)(?: for the Akeru harness)?\.(?:\s|$)/,+ );++ if (missingCredential?.[1]) {+ const requirement = missingCredential[1];++ return {+ title: provider+ ? t("{provider} needs {requirement}", { provider, requirement })+ : t("The provider needs {requirement}", { requirement }),+ description: t(+ "Add it to this provider in Settings > Providers, then send your message again.",+ ),+ technicalDetails: boundedTechnicalDetails(error),+ action: "providers",+ };+ }++ if (/Custom .+ credentials are not supported/.test(error)) {+ return {+ title: provider+ ? t("{provider} can't use custom credentials", { provider })+ : t("The provider can't use custom credentials"),+ description: t(+ "Use your account in Settings > Providers, or pick another model for this bot.",+ ),+ technicalDetails: boundedTechnicalDetails(error),+ action: "providers",+ };+ }+if (/network|connection|socket|fetch failed|disconnected/i.test(error)) {return {title: t("Connection interrupted"),diff --git a/packages/client-runtime/src/i18n/__snapshots__/coverage.test.ts.snap b/packages/client-runtime/src/i18n/__snapshots__/coverage.test.ts.snapindex 5181a3f90..dc35034ba 100644--- a/packages/client-runtime/src/i18n/__snapshots__/coverage.test.ts.snap+++ b/packages/client-runtime/src/i18n/__snapshots__/coverage.test.ts.snap@@ -2,7 +2,7 @@exports[`discovered interface message coverage > covers static calls and finite label sources without translating identifiers 1`] = `{- "directMessageCount": 1770,+ "directMessageCount": 1776,"expressions": {"apps/mobile/src/components/DictationControls.tsx": ["announcements[status]);",diff --git a/packages/client-runtime/src/i18n/catalogs/en/connections.ts b/packages/client-runtime/src/i18n/catalogs/en/connections.tsindex 952dfd859..c8e7cf999 100644--- a/packages/client-runtime/src/i18n/catalogs/en/connections.ts+++ b/packages/client-runtime/src/i18n/catalogs/en/connections.ts@@ -282,6 +282,15 @@ export const connectionsCatalog = {Export: "Export","Exporting...": "Exporting...","Import Akeru archive": "Import Akeru archive",+ "Open {provider} settings": "Open {provider} settings",+ "{provider} needs {requirement}": "{provider} needs {requirement}",+ "The provider needs {requirement}": "The provider needs {requirement}",+ "Add it to this provider in Settings > Providers, then send your message again.":+ "Add it to this provider in Settings > Providers, then send your message again.",+ "{provider} can't use custom credentials": "{provider} can't use custom credentials",+ "The provider can't use custom credentials": "The provider can't use custom credentials",+ "Use your account in Settings > Providers, or pick another model for this bot.":+ "Use your account in Settings > Providers, or pick another model for this bot.","{provider} is not connected": "{provider} is not connected","The provider is not connected": "The provider is not connected","Connect your {provider} account in Settings > Providers.":diff --git a/packages/client-runtime/src/i18n/catalogs/zh-CN/connections.ts b/packages/client-runtime/src/i18n/catalogs/zh-CN/connections.tsindex 421f5737f..63e9037bd 100644--- a/packages/client-runtime/src/i18n/catalogs/zh-CN/connections.ts+++ b/packages/client-runtime/src/i18n/catalogs/zh-CN/connections.ts@@ -263,6 +263,15 @@ export const connectionsCatalog = {Export: "导出","Exporting...": "正在导出…","Import Akeru archive": "导入 Akeru 归档",+ "Open {provider} settings": "打开 {provider} 设置",+ "{provider} needs {requirement}": "{provider} 需要 {requirement}",+ "The provider needs {requirement}": "提供商需要 {requirement}",+ "Add it to this provider in Settings > Providers, then send your message again.":+ "请在“设置 > 提供商”中为此提供商添加它,然后重新发送消息。",+ "{provider} can't use custom credentials": "{provider} 无法使用自定义凭据",+ "The provider can't use custom credentials": "提供商无法使用自定义凭据",+ "Use your account in Settings > Providers, or pick another model for this bot.":+ "请在“设置 > 提供商”中改用你的账户,或为此机器人选择其他模型。","{provider} is not connected": "{provider} 未连接","The provider is not connected": "提供商未连接","Connect your {provider} account in Settings > Providers.":diff --git a/packages/client-runtime/src/providerAvailability.test.ts b/packages/client-runtime/src/providerAvailability.test.tsindex 0dd262b55..8989cc1f9 100644--- a/packages/client-runtime/src/providerAvailability.test.ts+++ b/packages/client-runtime/src/providerAvailability.test.ts@@ -206,12 +206,20 @@ describe("latestTurnFailure", () => {activity({kind: "provider.turn.start.failed",createdAt: "2026-01-01T00:00:02.000Z",- payload: { detail: "OAuth token expired", unavailability: "expired-login" },+ payload: {+ detail: "OAuth token expired",+ unavailability: "expired-login",+ providerInstanceId: "codex",+ },}),],"2026-01-01T00:00:01.000Z",),- ).toEqual({ detail: "OAuth token expired", unavailability: "expired-login" });+ ).toEqual({+ detail: "OAuth token expired",+ unavailability: "expired-login",+ providerInstanceId: "codex",+ });});it("reads a mid-turn runtime error without a category", () => {diff --git a/packages/client-runtime/src/providerAvailability.ts b/packages/client-runtime/src/providerAvailability.tsindex ce18eeb2f..0d1ef6c37 100644--- a/packages/client-runtime/src/providerAvailability.ts+++ b/packages/client-runtime/src/providerAvailability.ts@@ -27,6 +27,15 @@ export interface ProviderAvailabilityPresentation {readonly description: string;readonly technicalDetails: string;readonly action: ProviderAvailabilityAction;+ /** Set when a known provider state caused the failure, so a client can name the fix. */+ readonly reason?: ProviderAvailabilityReason | undefined;+}++/** Whether signing in is the fix, so a repair button can say "Connect". */+export function providerReasonNeedsSignIn(+ reason: ProviderAvailabilityReason | null | undefined,+): boolean {+ return reason === "missing-login" || reason === "expired-login" || reason === "missing-provider";}export function providerAvailabilityReason(@@ -72,6 +81,13 @@ export type ProviderAvailabilityTranslate = (const englishTranslate: ProviderAvailabilityTranslate = createTranslator("en").t;export function presentProviderUnavailability(+ input: Parameters<typeof presentReason>[0],+ t: ProviderAvailabilityTranslate = englishTranslate,+): ProviderAvailabilityPresentation & { readonly reason: ProviderAvailabilityReason } {+ return { ...presentReason(input, t), reason: input.reason };+}++function presentReason(input: {readonly reason: ProviderAvailabilityReason;/** Omit when the failure did not say which provider it came from. */@@ -218,6 +234,8 @@ export function latestTurnFailure(): {readonly detail: string;readonly unavailability: ServerProviderUnavailability | null;+ /** The provider instance that failed, when the server recorded it. */+ readonly providerInstanceId?: string;} | null {// .sort() on a copy, not .toSorted(): Hermes doesn't ship the ES2023// change-by-copy array methods.@@ -245,6 +263,9 @@ export function latestTurnFailure(unavailability: isServerProviderUnavailability(payload.unavailability)? payload.unavailability: null,+ ...(Predicate.isString(payload.providerInstanceId)+ ? { providerInstanceId: payload.providerInstanceId }+ : {}),};}diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.tsindex 4855a1191..d90acb1ec 100644--- a/packages/contracts/src/model.ts+++ b/packages/contracts/src/model.ts@@ -248,3 +248,31 @@ export const PROVIDER_DISPLAY_NAMES: Partial<Record<ProviderDriverKind, string>>[OPENCODE_GO_DRIVER_KIND]: "OpenCode Go",[CUSTOM_OPENAI_DRIVER_KIND]: "Custom API",};++/**+ * The account a user signs in with for each built-in driver. Use in sign-in+ * and setup copy, where "Connect ChatGPT" means more than "Connect Codex".+ */+export const PROVIDER_ACCOUNT_NAMES: Partial<Record<ProviderDriverKind, string>> = {+ [CODEX_DRIVER_KIND]: "ChatGPT",+ [CLAUDE_DRIVER_KIND]: "Claude",+ [GROK_DRIVER_KIND]: "Grok",+ [KIMI_DRIVER_KIND]: "Kimi For Coding",+ [OPENCODE_DRIVER_KIND]: "OpenCode",+ [OPENCODE_GO_DRIVER_KIND]: "OpenCode Go",+};++/**+ * The account name for a built-in instance still using its stock name, so a+ * name the user chose ("Work Codex") wins over "ChatGPT". Undefined otherwise.+ */+export function stockProviderAccountName(+ driver: ProviderDriverKind,+ displayName: string | undefined,+): string | undefined {+ const name = displayName?.trim();++ return !name || name === PROVIDER_DISPLAY_NAMES[driver]+ ? PROVIDER_ACCOUNT_NAMES[driver]+ : undefined;+}