Add backend support for Copilot connection and account-status UX without introducing raw provider credential management. This change extends sidecar capabilities with explicit connection diagnostics, adds a refreshable capabilities IPC path, classifies common Copilot CLI failure modes, and includes a frontend handover document describing the new payload and expected UI states. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
6.1 KiB
Handover: Copilot connection status UI
This document is for the frontend/UX model that will build the user-facing experience on top of the backend changes implemented in this task.
Goal
Build UI for the roadmap's highest-priority backend work:
- show whether Kopaya can reach GitHub Copilot successfully
- explain why it cannot when something is wrong
- let the user refresh capability status after installing or logging into Copilot CLI
Do not build raw provider-secret management UI for this flow. Kopaya currently relies on the system-installed GitHub Copilot CLI rather than storing provider API keys itself.
Backend changes already implemented
1. SidecarCapabilities now includes connection diagnostics
File: src/shared/contracts/sidecar.ts
New field:
connection: {
status: 'ready' | 'copilot-cli-missing' | 'copilot-auth-required' | 'copilot-error';
summary: string;
detail?: string;
copilotCliPath?: string;
checkedAt: string;
}
This comes from the .NET sidecar and is included alongside runtime, modes, and models.
2. There is now a refreshable backend API
Files:
src/shared/contracts/ipc.tssrc/shared/contracts/channels.tssrc/preload/index.tssrc/main/ipc/registerIpcHandlers.tssrc/main/KopayaAppService.ts
New renderer-callable method:
window.kopayaApi.refreshSidecarCapabilities()
This bypasses the cached capability result in KopayaAppService and fetches a fresh capability payload from the sidecar. Use this for Retry / Refresh buttons after the user fixes CLI install or login state.
3. Sidecar diagnostics now distinguish common failure modes
Files:
sidecar/src/Kopaya.AgentHost/Services/CopilotCliPathResolver.cssidecar/src/Kopaya.AgentHost/Services/SidecarProtocolHost.cssidecar/src/Kopaya.AgentHost/Contracts/ProtocolModels.cs
The backend now reports:
ready: Copilot CLI was found and model listing succeededcopilot-cli-missing: Kopaya could not find thecopilotcommand onPATHcopilot-auth-required: Copilot CLI exists, but the error looks like login/auth is requiredcopilot-error: Copilot CLI exists, but model loading failed for another reason
4. Validation status
Validated successfully after the change:
bun testdotnet test sidecar\Kopaya.AgentHost.slnxusing an alternate build output path to avoid a locked local executable in the shared environment
Important architecture note
Kopaya currently does not manage provider credentials directly for this path.
The sidecar resolves the system-installed copilot command and uses that runtime. That means the near-term UI should be about:
- install state
- login state
- connection health
- model availability
- refresh / retry
It should not ask the user for OpenAI, Anthropic, or Google secrets as part of this specific Copilot status flow.
Current renderer integration point
File: src/renderer/App.tsx
On mount, the renderer already does:
api.describeSidecarCapabilities().then(setSidecarCapabilities)
This state is already stored in:
const [sidecarCapabilities, setSidecarCapabilities] = useState<SidecarCapabilities>();
So the frontend work is mostly about:
- reading
sidecarCapabilities.connection - rendering the right UX state
- calling
api.refreshSidecarCapabilities()when the user retries
Recommended UI states
ready
Show:
- positive connected state
- connection summary
- model count (
sidecarCapabilities.models.length) - optional advanced details like CLI path and last checked time
Good copy direction:
- "Connected to GitHub Copilot"
- "19 models available"
copilot-cli-missing
Show:
- an actionable install state
- summary from backend
- detail text in an expandable "technical details" area
- a Refresh button that calls
refreshSidecarCapabilities()
Good copy direction:
- "GitHub Copilot CLI not found"
- "Install the
copilotCLI and make sure it is available on PATH"
copilot-auth-required
Show:
- an actionable login state
- summary from backend
- technical details if available
- a Refresh button after the user logs in externally
Good copy direction:
- "GitHub Copilot needs sign-in"
- "Finish login in the Copilot CLI, then refresh"
copilot-error
Show:
- a generic error state
- summary from backend
detailin a technical details area- Refresh button
Good copy direction:
- "Kopaya found Copilot, but could not load models"
Recommended frontend implementation shape
Suggested state additions in App.tsx
- keep using the existing
sidecarCapabilitiesstate - add a small
isRefreshingCapabilitiesboolean state - create a refresh handler that calls
api.refreshSidecarCapabilities()
Example shape:
const refreshCapabilities = async () => {
setIsRefreshingCapabilities(true);
try {
const capabilities = await api.refreshSidecarCapabilities();
setSidecarCapabilities(capabilities);
} finally {
setIsRefreshingCapabilities(false);
}
};
Suggested component split
Any of these would be reasonable:
- a new
CopilotStatusCardin settings - a small status section near model/pattern settings
- a dedicated connectivity block in the settings panel
Suggested UX details
- treat
detailas secondary, not primary - show the backend
summaryprominently - expose CLI path only in advanced details
- keep the empty/loading state graceful
- do not block the rest of the app if capabilities are degraded
What is intentionally not implemented yet
These are still future enhancements, not part of this backend change:
- actual GitHub account or org identity reporting
- CLI version reporting
- an in-app "log in to Copilot" action
- push-based status updates when the external CLI state changes
- direct provider credential storage for OpenAI / Anthropic / Google
Suggested follow-up order for the frontend model
- Add a settings/status UI for
sidecarCapabilities.connection - Add a Refresh button using
refreshSidecarCapabilities() - Surface model count and summary in the connected state
- Add expandable technical details for
detailandcopilotCliPath - Keep future direct-provider credential UX separate from this Copilot flow