aryx/HANDOVER.md

Handover: Copilot version + account context UI

This document is for the frontend/UX agent that will extend the existing Copilot connection UI.

Goal

Build on top of the current Settings → AI Provider → Connection view so it can show:

• whether the installed Copilot CLI is current or outdated
• which GitHub account Copilot is currently using
• organization context when it can be discovered

Do not add provider-secret management for this flow. Kopaya still relies on the system-installed GitHub Copilot CLI.

Backend changes now implemented

1. SidecarCapabilities.connection has new structured fields

File: src/shared/contracts/sidecar.ts

New payload shape:

connection: {
  status: 'ready' | 'copilot-cli-missing' | 'copilot-auth-required' | 'copilot-error';
  summary: string;
  detail?: string;
  copilotCliPath?: string;
  checkedAt: string;
  copilotCliVersion?: {
    status: 'latest' | 'outdated' | 'unknown';
    installedVersion?: string;
    latestVersion?: string;
    detail?: string;
  };
  account?: {
    authenticated: boolean;
    login?: string;
    host?: string;
    authType?: string;
    statusMessage?: string;
    organizations?: string[];
  };
}

2. Version state is now resolved by the sidecar

Files:

• sidecar/src/Kopaya.AgentHost/Services/CopilotConnectionMetadataResolver.cs
• sidecar/src/Kopaya.AgentHost/Services/SidecarProtocolHost.cs

The sidecar now runs copilot version and classifies the result as:

• latest: the CLI explicitly reported that the install is current
• outdated: the CLI reported that a newer version is available
• unknown: the version command timed out, failed, or did not return a recognizable update state

Important nuance:

• this does not change connection.status
• connection.status still means install/auth/model-list health
• version freshness is a separate concern and should be rendered separately in the UI

3. Account context is now resolved by the sidecar

Files:

• sidecar/src/Kopaya.AgentHost/Services/CopilotConnectionMetadataResolver.cs
• sidecar/src/Kopaya.AgentHost/Services/SidecarProtocolHost.cs

The sidecar now uses the Copilot SDK auth-status call to populate:

• account.authenticated
• account.login
• account.host
• account.authType
• account.statusMessage

4. Organization context is best-effort

When the Copilot auth status provides a login + host, the sidecar also makes a best-effort gh CLI lookup for org memberships:

• it verifies the gh authenticated user matches the Copilot login on the same host
• if that succeeds, it fetches user/orgs
• those org logins are returned as account.organizations

Important nuance:

• organizations may be missing entirely
• that can mean gh is not installed, not authenticated, lacks read:org, timed out, or the accounts did not match
• the frontend should treat organizations as optional enhancement data, not a guaranteed field

Files changed

Backend / shared contracts:

• src/shared/contracts/sidecar.ts
• sidecar/src/Kopaya.AgentHost/Contracts/ProtocolModels.cs
• sidecar/src/Kopaya.AgentHost/Services/SidecarProtocolHost.cs
• sidecar/src/Kopaya.AgentHost/Services/CopilotConnectionMetadataResolver.cs

Tests:

• sidecar/tests/Kopaya.AgentHost.Tests/SidecarProtocolHostTests.cs
• sidecar/tests/Kopaya.AgentHost.Tests/CopilotConnectionMetadataResolverTests.cs

Validation status

Validated successfully after the change:

• bun test
• dotnet test sidecar\Kopaya.AgentHost.slnx -p:BaseOutputPath="<session-sidecar-build-path>"

Current renderer state

There is already a Copilot settings surface:

• src/renderer/components/SettingsPanel.tsx
• src/renderer/components/CopilotStatusCard.tsx

Current behavior:

• shows connection readiness / missing CLI / auth required / generic error
• shows model count, CLI path, and checked timestamp
• does not yet render the new copilotCliVersion or account fields

Recommended frontend follow-up

1. Show the active GitHub account prominently

Good options:

• a compact identity row like davidkaya · github.com
• a small pill/chip under the connection status
• a labeled metadata grid in the expanded details area

Suggested fallback behavior:

• if account.login exists, show it
• if account.host exists, show it next to the login
• if account.statusMessage exists but login is missing, use that as secondary text

2. Show CLI freshness as a separate badge/state

Recommended mapping:

• latest → subtle positive/neutral badge like Up to date
• outdated → amber warning badge like Update available
• unknown → low-emphasis muted label like Version unknown

Good details to show in the expanded area:

• installed version
• latest version (when known)
• raw detail text only as secondary / technical detail

3. Show organizations only when present

If account.organizations exists and has values:

• render them as small pills/tags
• cap the visible count if the list is long
• consider +N more if there are many

If it is missing:

• do not show an empty placeholder
• fall back to host/account info instead

4. Keep account/version separate from the main connection summary

Do not overload the existing top-level connection state.

Recommended mental model:

• main status row = “Can Kopaya use Copilot right now?”
• version badge = “Should the CLI be updated?”
• account info = “Who is Kopaya connected as?”
• org pills = “What org context is discoverable?”

Suggested UI copy

For account:

• Signed in as davidkaya
• github.com

For version:

• Copilot CLI is up to date
• Copilot CLI update available
• Could not determine Copilot CLI version

For orgs:

• Organizations

Non-goals of this backend change

Still not implemented:

• an in-app copilot update action
• an in-app copilot login action
• direct provider credentials for OpenAI / Anthropic / Google
• guaranteed authoritative “active organization” selection semantics

The new org data is “best effort discovered context,” not a firm entitlement model.