From 46b41386f9d44200b7d9cecf0537b985442aefba Mon Sep 17 00:00:00 2001 From: Jackson Chen <90215880+Sma1lboy@users.noreply.github.com> Date: Thu, 1 Oct 2026 04:37:21 -0700 Subject: [PATCH 1/5] fix(app): explain provider setup and refresh failures --- .github/workflows/provider-ux-copy.yml | 64 +++++++ docs/ux-review-providers.md | 27 +++ .../automation/verify-provider-guidance.mts | 158 ++++++++++++++++++ .../components/chat/ChannelEmptyState.tsx | 22 ++- .../components/settings/pages/agents-page.tsx | 4 +- .../settings/pages/general-page.tsx | 67 +++++--- .../libs/hooks/use-local-ai-providers.test.ts | 110 ++++++++++++ .../libs/hooks/use-local-ai-providers.ts | 34 ++-- .../src/renderer/libs/provider-status.test.ts | 40 +++++ .../app/src/renderer/libs/provider-status.ts | 38 +++-- 10 files changed, 512 insertions(+), 52 deletions(-) create mode 100644 .github/workflows/provider-ux-copy.yml create mode 100644 docs/ux-review-providers.md create mode 100644 packages/app/automation/verify-provider-guidance.mts create mode 100644 packages/app/src/renderer/libs/hooks/use-local-ai-providers.test.ts create mode 100644 packages/app/src/renderer/libs/provider-status.test.ts diff --git a/.github/workflows/provider-ux-copy.yml b/.github/workflows/provider-ux-copy.yml new file mode 100644 index 00000000..4b6e767a --- /dev/null +++ b/.github/workflows/provider-ux-copy.yml @@ -0,0 +1,64 @@ +name: Provider UX verification +on: + pull_request: + branches: [main] + paths: + - "packages/app/src/renderer/libs/provider-status*" + - "packages/app/src/renderer/libs/hooks/use-local-ai-providers*" + - "packages/app/src/renderer/components/chat/ChannelEmptyState.tsx" + - "packages/app/src/renderer/components/settings/pages/general-page.tsx" + - "packages/app/src/renderer/components/settings/pages/agents-page.tsx" + - "packages/app/automation/verify-provider-guidance.mts" + - ".github/workflows/provider-ux-copy.yml" +jobs: + provider-ux: + runs-on: macos-latest + timeout-minutes: 30 + permissions: + contents: read + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: "22" + - uses: pnpm/action-setup@v4 + - name: Install locked dependencies + run: pnpm install --frozen-lockfile + - name: Test provider status and refresh recovery + working-directory: packages/app + run: pnpm exec vitest run src/renderer/libs/provider-status.test.ts src/renderer/libs/hooks/use-local-ai-providers.test.ts + - name: Prepare actual Electron app + run: pnpm --filter @convera/app automation:prepare + - name: Verify provider setup in isolated Electron profile + working-directory: packages/app + env: + UX_VARIANT: after + run: pnpm exec tsx automation/verify-provider-guidance.mts + - name: Prepare baseline checkout + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + run: | + git worktree add "$RUNNER_TEMP/convera-before" "$BASE_SHA" + ln -s "$GITHUB_WORKSPACE/node_modules" "$RUNNER_TEMP/convera-before/node_modules" + if [ -d "$GITHUB_WORKSPACE/packages/app/node_modules" ]; then + ln -s "$GITHUB_WORKSPACE/packages/app/node_modules" "$RUNNER_TEMP/convera-before/packages/app/node_modules" + fi + - name: Prepare baseline Electron app + working-directory: ${{ runner.temp }}/convera-before + run: pnpm --filter @convera/app automation:prepare + - name: Capture actual baseline with the same scenario + working-directory: ${{ runner.temp }}/convera-before/packages/app + env: + UX_VARIANT: before + run: EVIDENCE_DIR="$GITHUB_WORKSPACE/packages/app/.automation/ux-evidence" pnpm exec tsx "$GITHUB_WORKSPACE/packages/app/automation/verify-provider-guidance.mts" + - name: Upload native verification evidence + if: always() + uses: actions/upload-artifact@v4 + with: + name: convera-provider-ux-evidence + path: | + packages/app/.automation/ux-evidence + packages/app/.automation/logs + if-no-files-found: error diff --git a/docs/ux-review-providers.md b/docs/ux-review-providers.md new file mode 100644 index 00000000..08ca4041 --- /dev/null +++ b/docs/ux-review-providers.md @@ -0,0 +1,27 @@ +# Provider and memory guidance review + +Scope: first-use channel copy, provider selection/checking, settings, memory privacy/cost expectations. Source baseline: `0e21210e7f9bcfb6164c95b53338621a98e46cb6`. The UX-writing skill at https://www.skills.sh/content-designer/ux-writing-skill/ux-writing was read, including its full upstream SKILL.md. Copy was reviewed for purpose, concision, conversational tone and factual clarity. + +## Before → after + +- “Local AI Providers” implied local inference → “AI providers”, with local history and external provider processing explained +- Missing API key / CLI status was a dead end → names the required environment variable or install/sign-in step and how to re-check +- Merely present API keys showed “Ready” → “Configured”, with usage-charge context, without claiming key validation +- Re-check did not re-enter loading, rejected checks were unhandled and could leave stale ready badges → visible checking/error/retry states; failed checks clear stale availability and older results cannot overwrite a newer check +- “Selected/Select” left the scope unclear → “Default/Use by default/Setup required”, with separate colleague-level provider choice explained +- Channel empty state claimed “Nobody here can answer” based only on the default provider → names that provider’s setup need and explains colleague-specific choices; checking no longer displays a false failure +- Suggestions did not explain their behavior → “Choose a suggestion to edit before sending” +- Local memory copy obscured background AI processing → explains that completed turns are sent to the chosen curator and provider charges may apply +- Missing memory status displayed zero pending/failed jobs → “Status unavailable”; memory load errors provide Reload memory settings + +## Verification + +- Eight new tests exercise provider status guidance, missing bridge, rejected/unsuccessful IPC, stale-ready clearing, retry, checking, and out-of-order responses +- Full unit suite: 586 passed, 3 existing skipped in the cloud checkout +- `Provider UX verification` builds and drives the actual Electron app through the repository’s automation MCP on macOS, in isolated before/after profiles +- Native scenario: open settings, observe unavailable OpenAI API and its disabled choice, re-check, inspect memory guidance and capture screenshots; no credentials or billable model requests +- Evidence: `{before,after}-{workspace,provider-settings,memory-settings}.png` and matching `*-automation.json` + +## Boundaries + +Cloud-local `automation:prepare` is blocked by a Unix-socket EPERM; the CI scenario supplies the real-machine check. Local whole-app type-check was terminated by the environment, so unit results do not imply that check passed. No configured-provider chat, AI output quality, MCP service account, memory curation request, production rollout or macOS security change is exercised. CI errors fail visibly; they are not converted into a success result. diff --git a/packages/app/automation/verify-provider-guidance.mts b/packages/app/automation/verify-provider-guidance.mts new file mode 100644 index 00000000..21953f0d --- /dev/null +++ b/packages/app/automation/verify-provider-guidance.mts @@ -0,0 +1,158 @@ +import assert from "node:assert/strict"; +import { copyFile, mkdir, rm, writeFile } from "node:fs/promises"; +import path from "node:path"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; + +const appRoot = process.cwd(); +const variant = process.env.UX_VARIANT ?? "after"; +const profileId = `ux-copy-${variant}`; +const evidenceDir = path.resolve( + process.env.EVIDENCE_DIR ?? ".automation/ux-evidence", +); +await mkdir(evidenceDir, { recursive: true }); +const env = Object.fromEntries( + Object.entries(process.env).filter( + (entry): entry is [string, string] => typeof entry[1] === "string", + ), +); +// This verifies provider setup without credentials or billable model requests. +delete env.OPENAI_API_KEY; +delete env.FIREWORKS_API_KEY; +const transport = new StdioClientTransport({ + command: "pnpm", + args: ["automation"], + cwd: appRoot, + env, + stderr: "pipe", +}); +const client = new Client({ + name: "convera-ux-verification", + version: "1.0.0", +}); +const log: unknown[] = []; +async function call(name: string, args: Record) { + const result = await client.callTool({ name, arguments: args }, undefined, { + timeout: 120000, + }); + const blocks = result.content as Array<{ type: string; text?: string }>; + const body = blocks.find((block) => block.type === "text")?.text; + const parsed = body ? JSON.parse(body) : null; + log.push({ name, args, result: parsed }); + await writeFile( + path.join(evidenceDir, `${variant}-automation.json`), + JSON.stringify(log, null, 2), + ); + assert.ok(!result.isError && parsed?.ok, JSON.stringify(parsed)); + return parsed.data; +} +async function capture(name: string) { + const shot = await call("convera_observe", { action: "screenshot" }); + await copyFile( + shot.filePath, + path.join(evidenceDir, `${variant}-${name}.png`), + ); +} +async function find(name: string) { + const elements = await call("convera_observe", { + action: "snapshot", + max_elements: 500, + }); + const element = elements.find((item: { name: string }) => item.name === name); + assert.ok(element, `Missing visible control: ${name}`); + return element.selector as string; +} +let launched = false; +try { + await client.connect(transport); + await call("convera_session", { action: "launch", profile_id: profileId }); + launched = true; + await call("convera_wait", { + condition: "displayed", + selector: 'button[aria-label="Open settings"]', + timeout_ms: 60000, + }); + await call("convera_observe", { action: "snapshot", max_elements: 500 }); + await capture("workspace"); + await call("convera_interact", { + action: "click", + selector: await find("Open settings"), + }); + await call("convera_wait", { + condition: "exists", + selector: '[data-testid="local-ai-provider-openai-api"]', + timeout_ms: 60000, + }); + const providerSelector = '[data-testid="local-ai-provider-openai-api"]'; + await call("convera_wait", { + condition: "text_contains", + selector: providerSelector, + text: "No API key", + timeout_ms: 60000, + }); + await call("convera_interact", { + action: "scroll", + selector: providerSelector, + }); + const provider = await call("convera_observe", { + action: "element", + selector: providerSelector, + }); + assert.equal(provider.enabled, false); + if (variant === "after") + assert.match(provider.text, /Set OPENAI_API_KEY.*restart Convera/); + await capture("provider-settings"); + const refreshSelector = await find("Re-check providers"); + await call("convera_interact", { + action: "click", + selector: refreshSelector, + }); + await call("convera_wait", { + condition: "enabled", + selector: refreshSelector, + timeout_ms: 60000, + }); + await call("convera_wait", { + condition: "text_contains", + selector: providerSelector, + text: "No API key", + timeout_ms: 60000, + }); + const memorySelector = await find("Background curator"); + await call("convera_interact", { + action: "scroll", + selector: memorySelector, + }); + const body = await call("convera_observe", { + action: "element", + selector: "body", + }); + if (variant === "after") + assert.match(body.text, /completed turns are sent|Sends completed turns/); + await capture("memory-settings"); + // Leave settings and return without changing any provider or memory choice. + const snapshot = await call("convera_observe", { + action: "snapshot", + max_elements: 500, + }); + const back = snapshot.find((item: { name: string }) => + /back to (workspace|chat)/i.test(item.name), + ); + if (back) { + await call("convera_interact", { + action: "click", + selector: back.selector, + }); + await call("convera_observe", { action: "snapshot", max_elements: 500 }); + } +} finally { + try { + if (launched) await call("convera_session", { action: "close" }); + } finally { + await client.close(); + } + await rm(path.join(appRoot, ".automation", "profiles", profileId), { + recursive: true, + force: true, + }); +} diff --git a/packages/app/src/renderer/components/chat/ChannelEmptyState.tsx b/packages/app/src/renderer/components/chat/ChannelEmptyState.tsx index 633ba456..a23bbecd 100644 --- a/packages/app/src/renderer/components/chat/ChannelEmptyState.tsx +++ b/packages/app/src/renderer/components/chat/ChannelEmptyState.tsx @@ -52,7 +52,7 @@ export function ChannelEmptyState({ // Every starter colleague is pinned to this provider at hire time, so a // missing key here means nobody in the room can answer — worth saying before // the user types into a room that will stay silent. - const { providers, loading } = useLocalAIProviders(); + const { providers, loading, error } = useLocalAIProviders(); const provider = providers.find( (candidate) => candidate.id === DEFAULT_LOCAL_AI_PROVIDER_ID, ); @@ -95,16 +95,19 @@ export function ChannelEmptyState({ ))}

- They read this room like you do and answer when spoken to. Mention - one by name to ask them directly, or say something to nobody in - particular and whoever fits will pick it up. + Mention a colleague by name to ask them directly. For a general + message, each colleague decides whether to reply. Their AI provider + must be configured before they can answer.

)}
+

+ Choose a suggestion to edit before sending. +

- Try + Add a starter message

{prompts.map((prompt) => ( {" "} - to set one up. + to check providers. Colleagues may have a different provider set in + Agents.

)} diff --git a/packages/app/src/renderer/components/settings/pages/agents-page.tsx b/packages/app/src/renderer/components/settings/pages/agents-page.tsx index 23c2e99a..61510f7a 100644 --- a/packages/app/src/renderer/components/settings/pages/agents-page.tsx +++ b/packages/app/src/renderer/components/settings/pages/agents-page.tsx @@ -337,8 +337,8 @@ const AgentFormFields = ({

) : (

- Each colleague can run on its own model — a reviewer on a stronger - one, a note-taker on something cheap. + This choice applies to this colleague. Messages and context go to + the selected provider; its terms and usage charges apply.

)} diff --git a/packages/app/src/renderer/components/settings/pages/general-page.tsx b/packages/app/src/renderer/components/settings/pages/general-page.tsx index 894db211..f8c97724 100644 --- a/packages/app/src/renderer/components/settings/pages/general-page.tsx +++ b/packages/app/src/renderer/components/settings/pages/general-page.tsx @@ -63,6 +63,7 @@ export function GeneralSettingsPage() { const { providers, loading: providersLoading, + error: providersError, refresh: refreshProviders, } = useLocalAIProviders(); const [memorySettings, setMemorySettings] = @@ -363,19 +364,19 @@ export function GeneralSettingsPage() { General

- Configure keyboard shortcuts and general preferences + Manage keyboard shortcuts, AI providers and memory

- {/* Keyboard Shortcuts Section */} + {/* Keyboard shortcuts Section */}

- Keyboard Shortcuts + Keyboard shortcuts

@@ -435,13 +436,14 @@ export function GeneralSettingsPage() {

- Local AI Providers + AI providers

- Choose the provider Convera uses for new chats. An agent pinned to - a provider listed here as unavailable cannot answer. Your - selection is stored only on this device. + Choose a default for new chats. Colleagues with their own provider + keep that choice; change it in Agents. Chat history is stored + locally, but messages and context are sent to the selected + provider. Provider terms and usage charges apply.

+ {providersError && ( +

+ {providersError} +

+ )}
{providers.map((provider) => { const isSelected = provider.id === defaultConfigId; @@ -507,7 +514,11 @@ export function GeneralSettingsPage() { }`} > {isSelected && } - {isSelected ? "Selected" : "Select"} + {isSelected + ? "Default" + : canSelect + ? "Use by default" + : "Setup required"}
@@ -521,12 +532,12 @@ export function GeneralSettingsPage() {

- Memory and Context + Memory and context

- Store memory locally. An isolated provider session can curate - completed turns without blocking the reply. + Save memory on this device. If you enable a background curator, + completed turns are sent to that AI provider to update memory.

@@ -537,8 +548,9 @@ export function GeneralSettingsPage() { Memory provider

- Off pauses memory without deleting it. Local keeps memory on - this device. + Off pauses memory without deleting saved memories. Local + stores memories on this device; AI processing may use a + provider.

)} -
+
Memory status @@ -685,10 +700,20 @@ export function GeneralSettingsPage() { {memorySaving ? "Saving…" - : `${memoryStatus?.health ?? "unknown"} · ${ - memoryStatus?.pendingJobs ?? 0 - } pending · ${memoryStatus?.failedJobs ?? 0} failed`} + : memoryStatus + ? `${memoryStatus.health} · ${memoryStatus.pendingJobs} pending · ${memoryStatus.failedJobs} failed` + : "Status unavailable"} + {memoryError && ( + + )}
diff --git a/packages/app/src/renderer/libs/hooks/use-local-ai-providers.test.ts b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.test.ts new file mode 100644 index 00000000..693c1fd3 --- /dev/null +++ b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.test.ts @@ -0,0 +1,110 @@ +// @vitest-environment jsdom +import { act, createElement } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { useLocalAIProviders } from "./use-local-ai-providers"; +import type { ILocalAIAPI } from "@/shared/types/local-ai"; +// Use the app’s React and ReactDOM pair. The workspace’s testing-library +// installation brings a second React copy through the website’s dependencies. +let root: Root | undefined; +let container: HTMLDivElement | undefined; +( + globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } +).IS_REACT_ACT_ENVIRONMENT = true; +async function renderHook(hook: typeof useLocalAIProviders) { + const result = { current: undefined as unknown as ReturnType }; + function Probe() { + result.current = hook(); + return null; + } + container = document.createElement("div"); + document.body.appendChild(container); + root = createRoot(container); + await act(async () => { + root!.render(createElement(Probe)); + }); + return { result }; +} +async function waitFor(assertion: () => void) { + await act(async () => {}); + assertion(); +} +const ready = [ + { + id: "openai-api", + name: "OpenAI API", + kind: "openai-api", + availability: "available", + }, +]; +const setup = (listProviders: ReturnType) => { + Object.defineProperty(window, "localAI", { + configurable: true, + value: { listProviders } as unknown as ILocalAIAPI, + }); +}; +afterEach(async () => { + await act(async () => root?.unmount()); + container?.remove(); + root = undefined; + Object.defineProperty(window, "localAI", { + configurable: true, + value: undefined, + }); +}); + +describe("provider refresh feedback", () => { + it("reports a missing bridge without an unhandled rejection", async () => { + const { result } = await renderHook(useLocalAIProviders); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(result.current.error).toContain("restart Convera"); + expect( + result.current.providers.every((p) => p.availability === "unavailable"), + ).toBe(true); + }); + it("clears stale ready statuses after failure and recovers on retry", async () => { + const list = vi + .fn() + .mockResolvedValueOnce({ success: true, data: ready }) + .mockRejectedValueOnce(new Error("offline")) + .mockResolvedValueOnce({ success: true, data: ready }); + setup(list); + const { result } = await renderHook(useLocalAIProviders); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(result.current.providers[0].availability).toBe("available"); + await act(() => result.current.refresh()); + expect(result.current.error).toContain("Re-check providers"); + expect( + result.current.providers.every((p) => p.availability === "unavailable"), + ).toBe(true); + await act(() => result.current.refresh()); + expect(result.current.error).toBeNull(); + expect(result.current.providers[0].availability).toBe("available"); + }); + it("shows checking while refreshing and ignores older results", async () => { + let resolveOlder!: (value: unknown) => void; + const list = vi + .fn() + .mockImplementationOnce( + () => + new Promise((resolve) => { + resolveOlder = resolve; + }), + ) + .mockResolvedValueOnce({ success: true, data: ready }); + setup(list); + const { result } = await renderHook(useLocalAIProviders); + expect(result.current.loading).toBe(true); + await act(() => result.current.refresh()); + await act(async () => resolveOlder({ success: false })); + expect(result.current.error).toBeNull(); + expect(result.current.providers[0].availability).toBe("available"); + }); + it("handles unsuccessful IPC responses as a visible failed check", async () => { + setup(vi.fn().mockResolvedValue({ success: false })); + const { result } = await renderHook(useLocalAIProviders); + await waitFor(() => expect(result.current.loading).toBe(false)); + expect(result.current.error).toContain("Couldn’t check"); + }); +}); diff --git a/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts index 1a52f73c..3faa7248 100644 --- a/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts +++ b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts @@ -1,4 +1,4 @@ -import { useCallback, useEffect, useState } from "react"; +import { useCallback, useEffect, useRef, useState } from "react"; import type { LocalAIProviderStatus } from "@/shared/types/local-ai"; import { getLocalAI, @@ -19,28 +19,42 @@ export function useLocalAIProviders() { const [providers, setProviders] = useState(fallbackProviders); const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const requestId = useRef(0); const refresh = useCallback(async () => { + const currentRequest = ++requestId.current; + setLoading(true); + setError(null); const localAI = getLocalAI(); - if (!localAI) { - setProviders(fallbackProviders); - setLoading(false); - return; - } try { + if (!localAI) throw new Error("Provider connection unavailable"); const result = await localAI.listProviders(); - if (result.success && result.data) { - setProviders(result.data); + if (!result.success || !result.data) + throw new Error("Provider check failed"); + if (currentRequest === requestId.current) setProviders(result.data); + } catch { + if (currentRequest === requestId.current) { + // Do not leave a stale “Ready” badge after a failed refresh. + setProviders(fallbackProviders); + setError( + "Couldn’t check AI providers. Re-check providers or restart Convera.", + ); } } finally { - setLoading(false); + if (currentRequest === requestId.current) setLoading(false); } }, []); useEffect(() => { void refresh(); + return () => { + // This ref is a request sequence, not a DOM node. Invalidate any in-flight check. + // eslint-disable-next-line react-hooks/exhaustive-deps + ++requestId.current; + }; }, [refresh]); - return { providers, loading, refresh }; + return { providers, loading, error, refresh }; } diff --git a/packages/app/src/renderer/libs/provider-status.test.ts b/packages/app/src/renderer/libs/provider-status.test.ts new file mode 100644 index 00000000..0b727947 --- /dev/null +++ b/packages/app/src/renderer/libs/provider-status.test.ts @@ -0,0 +1,40 @@ +import { describe, expect, it } from "vitest"; +import { describeProviderStatus } from "./provider-status"; + +describe("provider guidance", () => { + it("does not claim a configured API key has been validated", () => { + expect( + describeProviderStatus({ kind: "openai-api", availability: "available" }), + ).toMatchObject({ label: "Configured", ready: true }); + }); + it.each([ + ["openai-api", "OPENAI_API_KEY"], + ["fireworks-api", "FIREWORKS_API_KEY"], + ] as const)("explains setup for %s", (kind, variable) => { + const status = describeProviderStatus({ + kind, + availability: "missing", + detail: `${variable} not set`, + }); + expect(status.ready).toBe(false); + expect(status.hint).toContain(variable); + expect(status.hint).toContain("restart Convera"); + }); + it("explains sign-in recovery and distinguishes checks from setup", () => { + expect( + describeProviderStatus({ + kind: "codex-cli", + availability: "unauthenticated", + }).hint, + ).toContain("Sign in with Codex"); + expect( + describeProviderStatus({ kind: "codex-cli", availability: "error" }).hint, + ).toContain("Re-check providers"); + expect( + describeProviderStatus( + { kind: "openai-api", availability: "available" }, + true, + ), + ).toMatchObject({ label: "Checking…", ready: false }); + }); +}); diff --git a/packages/app/src/renderer/libs/provider-status.ts b/packages/app/src/renderer/libs/provider-status.ts index a752602e..ee470819 100644 --- a/packages/app/src/renderer/libs/provider-status.ts +++ b/packages/app/src/renderer/libs/provider-status.ts @@ -28,39 +28,57 @@ export function describeProviderStatus( loading = false, ): ProviderStatusDescription { if (loading) { - return { label: "Checking", ready: false }; + return { + label: "Checking…", + ready: false, + hint: "Checking provider setup…", + }; } const keyed = KEYED_KINDS.has(provider.kind); switch (provider.availability) { case "available": - return { label: "Ready", ready: true, hint: provider.detail }; + return { + label: keyed ? "Configured" : "Ready", + ready: true, + hint: keyed + ? "API key configured. Provider usage charges may apply." + : provider.detail, + }; case "unauthenticated": return { label: "Sign-in required", ready: false, - hint: provider.detail ?? "This provider is not signed in.", + hint: + provider.kind === "codex-cli" + ? "Sign in with Codex in Terminal, then re-check providers." + : provider.kind === "claude-code" + ? "Sign in with Claude Code in Terminal, then re-check providers." + : "Sign in with this provider, then re-check providers.", }; case "missing": return { label: keyed ? "No API key" : "Not installed", ready: false, hint: - provider.detail ?? - (keyed - ? "No API key is set for this provider." - : "The command-line tool for this provider was not found."), + provider.kind === "openai-api" + ? "Set OPENAI_API_KEY in Convera’s environment, then restart Convera." + : provider.kind === "fireworks-api" + ? "Set FIREWORKS_API_KEY in Convera’s environment, then restart Convera." + : keyed + ? "Configure this provider’s API key, then re-check providers." + : "Install and sign in to this provider’s command-line tool, then re-check providers.", }; case "error": return { - label: "Error", + label: "Check failed", ready: false, - hint: provider.detail ?? "Checking this provider failed.", + hint: "Couldn’t check this provider. Re-check providers or restart Convera.", }; default: return { label: "Unavailable", ready: false, - hint: provider.detail, + hint: provider.detail ?? "Re-check providers or restart Convera.", }; } } From 6719b765b8eea27e31c12cbff5984ada62c873b9 Mon Sep 17 00:00:00 2001 From: Jackson Chen <90215880+Sma1lboy@users.noreply.github.com> Date: Thu, 1 Oct 2026 04:40:32 -0700 Subject: [PATCH 2/5] test(app): keep request cancellation compatible with React lint --- .../renderer/libs/hooks/use-local-ai-providers.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts index 3faa7248..880db513 100644 --- a/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts +++ b/packages/app/src/renderer/libs/hooks/use-local-ai-providers.ts @@ -47,14 +47,14 @@ export function useLocalAIProviders() { } }, []); + const cancelPending = useCallback(() => { + requestId.current += 1; + }, []); + useEffect(() => { void refresh(); - return () => { - // This ref is a request sequence, not a DOM node. Invalidate any in-flight check. - // eslint-disable-next-line react-hooks/exhaustive-deps - ++requestId.current; - }; - }, [refresh]); + return cancelPending; + }, [refresh, cancelPending]); return { providers, loading, error, refresh }; } From 5ddb703b265ca7e3198df15e9c77be5b4778b337 Mon Sep 17 00:00:00 2001 From: Jackson Chen <90215880+Sma1lboy@users.noreply.github.com> Date: Thu, 1 Oct 2026 04:44:13 -0700 Subject: [PATCH 3/5] test(app): detect incomplete Electron builds and retain failure evidence --- .github/workflows/provider-ux-copy.yml | 19 +++++++++++++++++-- .../automation/verify-provider-guidance.mts | 18 ++++++++++++++++++ 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/.github/workflows/provider-ux-copy.yml b/.github/workflows/provider-ux-copy.yml index 4b6e767a..8d3f9246 100644 --- a/.github/workflows/provider-ux-copy.yml +++ b/.github/workflows/provider-ux-copy.yml @@ -14,6 +14,8 @@ jobs: provider-ux: runs-on: macos-latest timeout-minutes: 30 + env: + NODE_OPTIONS: --max-old-space-size=4096 permissions: contents: read steps: @@ -30,7 +32,14 @@ jobs: working-directory: packages/app run: pnpm exec vitest run src/renderer/libs/provider-status.test.ts src/renderer/libs/hooks/use-local-ai-providers.test.ts - name: Prepare actual Electron app - run: pnpm --filter @convera/app automation:prepare + run: | + set -euo pipefail + mkdir -p packages/app/.automation/ux-evidence + pnpm --filter @convera/app automation:prepare 2>&1 | tee packages/app/.automation/ux-evidence/after-build.log + ! grep -E 'FATAL ERROR|heap out of memory' packages/app/.automation/ux-evidence/after-build.log + test -s packages/app/.vite/renderer/main_window/index.html + test -s packages/app/.vite/build/preload.js + test -s packages/app/.vite/build/main.js - name: Verify provider setup in isolated Electron profile working-directory: packages/app env: @@ -47,7 +56,13 @@ jobs: fi - name: Prepare baseline Electron app working-directory: ${{ runner.temp }}/convera-before - run: pnpm --filter @convera/app automation:prepare + run: | + set -euo pipefail + pnpm --filter @convera/app automation:prepare 2>&1 | tee "$GITHUB_WORKSPACE/packages/app/.automation/ux-evidence/before-build.log" + ! grep -E 'FATAL ERROR|heap out of memory' "$GITHUB_WORKSPACE/packages/app/.automation/ux-evidence/before-build.log" + test -s packages/app/.vite/renderer/main_window/index.html + test -s packages/app/.vite/build/preload.js + test -s packages/app/.vite/build/main.js - name: Capture actual baseline with the same scenario working-directory: ${{ runner.temp }}/convera-before/packages/app env: diff --git a/packages/app/automation/verify-provider-guidance.mts b/packages/app/automation/verify-provider-guidance.mts index 21953f0d..cd396dfa 100644 --- a/packages/app/automation/verify-provider-guidance.mts +++ b/packages/app/automation/verify-provider-guidance.mts @@ -67,6 +67,7 @@ try { await client.connect(transport); await call("convera_session", { action: "launch", profile_id: profileId }); launched = true; + await call("convera_observe", { action: "snapshot", max_elements: 500 }); await call("convera_wait", { condition: "displayed", selector: 'button[aria-label="Open settings"]', @@ -145,6 +146,23 @@ try { }); await call("convera_observe", { action: "snapshot", max_elements: 500 }); } +} catch (error) { + if (launched) { + // Keep diagnostic evidence without turning a failed assertion into success. + for (const action of ["snapshot", "logs"] as const) { + try { + await call("convera_observe", { action, max_elements: 500 }); + } catch (diagnosticError) { + log.push({ diagnosticError: String(diagnosticError) }); + } + } + try { + await capture("failure"); + } catch (diagnosticError) { + log.push({ diagnosticError: String(diagnosticError) }); + } + } + throw error; } finally { try { if (launched) await call("convera_session", { action: "close" }); From edf3cbaff370ef3c8261770cb22ba1d67102cbc9 Mon Sep 17 00:00:00 2001 From: Jackson Chen <90215880+Sma1lboy@users.noreply.github.com> Date: Thu, 1 Oct 2026 04:55:17 -0700 Subject: [PATCH 4/5] test(app): frame full settings sections in native evidence --- packages/app/automation/verify-provider-guidance.mts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/app/automation/verify-provider-guidance.mts b/packages/app/automation/verify-provider-guidance.mts index cd396dfa..7df661df 100644 --- a/packages/app/automation/verify-provider-guidance.mts +++ b/packages/app/automation/verify-provider-guidance.mts @@ -67,6 +67,13 @@ try { await client.connect(transport); await call("convera_session", { action: "launch", profile_id: profileId }); launched = true; + // The semantic toolset has no resize action. Resize only this isolated + // Electron window so screenshots include the complete settings section. + await call("convera_execute", { + context: "main", + script: + "const window = electron.BrowserWindow.getAllWindows()[0]; window.setSize(1100, 850); return window.getSize();", + }); await call("convera_observe", { action: "snapshot", max_elements: 500 }); await call("convera_wait", { condition: "displayed", From 1cd26f4d123df0b6d5699eb6b0cd2bdf69069b08 Mon Sep 17 00:00:00 2001 From: Jackson Chen <90215880+Sma1lboy@users.noreply.github.com> Date: Thu, 1 Oct 2026 04:56:36 -0700 Subject: [PATCH 5/5] test(app): center evidence on provider and memory headings --- .../app/automation/verify-provider-guidance.mts | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/packages/app/automation/verify-provider-guidance.mts b/packages/app/automation/verify-provider-guidance.mts index 7df661df..5d014a7f 100644 --- a/packages/app/automation/verify-provider-guidance.mts +++ b/packages/app/automation/verify-provider-guidance.mts @@ -98,9 +98,16 @@ try { text: "No API key", timeout_ms: 60000, }); + const settingsBody = await call("convera_observe", { + action: "element", + selector: "body", + }); + const providerHeading = + variant === "before" ? "Local AI Providers" : "AI providers"; + assert.ok(settingsBody.text.includes(providerHeading)); await call("convera_interact", { action: "scroll", - selector: providerSelector, + selector: `//h2[normalize-space()="${providerHeading}"]`, }); const provider = await call("convera_observe", { action: "element", @@ -126,10 +133,13 @@ try { text: "No API key", timeout_ms: 60000, }); - const memorySelector = await find("Background curator"); + await find("Background curator"); + const memoryHeading = + variant === "before" ? "Memory and Context" : "Memory and context"; + assert.ok(settingsBody.text.includes(memoryHeading)); await call("convera_interact", { action: "scroll", - selector: memorySelector, + selector: `//h2[normalize-space()="${memoryHeading}"]`, }); const body = await call("convera_observe", { action: "element",