feat(app): provider system overhaul with model selector, diagnostics, and UX polish

- Add CombinedModelSelector with two-level drill-down (providers → models),
  favorites section, search, and single-provider auto-drill mode
- Add provider snapshot system (ProviderSnapshotManager) for cached provider/model state
- Add provider diagnostics with resolved binary paths and versions across all providers
- Add StatusBadge shared component for consistent status visual language
- Add ProviderDiagnosticSheet for detailed provider health inspection
- Add desktop auto-focus on input after any status bar interaction (model, mode,
  thinking, features) using focusWithRetries
- Fix Combobox flicker on height change by switching to bottom-based CSS positioning
  once initial floating-ui position resolves
- Add dynamic dropdown height: Level 1 fits content, Level 2 calculates from model count
- Remove "Other providers" section from model selector (only show available providers)

packages/server/src/client/daemon-client.ts

@@ -43,6 +43,9 @@ import type {
   ListAvailableProvidersResponse,
   ListTerminalsResponse,
   CreateTerminalResponse,
+  GetProvidersSnapshotResponseMessage,
+  ProviderDiagnosticResponseMessage,
+  RefreshProvidersSnapshotResponseMessage,
   SubscribeTerminalResponse,
   TerminalState,
   CloseItemsResponse,
@@ -147,6 +150,10 @@ export type DaemonEvent =
       requestId: string;
       resolution: AgentPermissionResponse;
     }
+  | {
+      type: "providers_snapshot_update";
+      payload: Extract<SessionOutboundMessage, { type: "providers_snapshot_update" }>["payload"];
+    }
   | { type: "error"; message: string };
 
 export type DaemonEventHandler = (event: DaemonEvent) => void;
@@ -222,6 +229,9 @@ type ListProviderFeaturesPayload = ListProviderFeaturesResponseMessage["payload"
 type ListProviderModelsPayload = ListProviderModelsResponseMessage["payload"];
 type ListProviderModesPayload = ListProviderModesResponseMessage["payload"];
 type ListAvailableProvidersPayload = ListAvailableProvidersResponse["payload"];
+type GetProvidersSnapshotPayload = GetProvidersSnapshotResponseMessage["payload"];
+type RefreshProvidersSnapshotPayload = RefreshProvidersSnapshotResponseMessage["payload"];
+type ProviderDiagnosticPayload = ProviderDiagnosticResponseMessage["payload"];
 type ListCommandsPayload = ListCommandsResponse["payload"];
 type ListCommandsDraftConfig = Pick<
   AgentSessionConfig,
@@ -2552,6 +2562,51 @@ export class DaemonClient {
     });
   }
 
+  async getProvidersSnapshot(options?: {
+    cwd?: string;
+    requestId?: string;
+  }): Promise<GetProvidersSnapshotPayload> {
+    return this.sendCorrelatedSessionRequest({
+      requestId: options?.requestId,
+      message: {
+        type: "get_providers_snapshot_request",
+        cwd: options?.cwd,
+      },
+      responseType: "get_providers_snapshot_response",
+      timeout: 10000,
+    });
+  }
+
+  async refreshProvidersSnapshot(options?: {
+    cwd?: string;
+    requestId?: string;
+  }): Promise<RefreshProvidersSnapshotPayload> {
+    return this.sendCorrelatedSessionRequest({
+      requestId: options?.requestId,
+      message: {
+        type: "refresh_providers_snapshot_request",
+        cwd: options?.cwd,
+      },
+      responseType: "refresh_providers_snapshot_response",
+      timeout: 5000,
+    });
+  }
+
+  async getProviderDiagnostic(
+    provider: AgentProvider,
+    options?: { requestId?: string },
+  ): Promise<ProviderDiagnosticPayload> {
+    return this.sendCorrelatedSessionRequest({
+      requestId: options?.requestId,
+      message: {
+        type: "provider_diagnostic_request",
+        provider,
+      },
+      responseType: "provider_diagnostic_response",
+      timeout: 30000,
+    });
+  }
+
   async listCommands(agentId: string, requestId?: string): Promise<ListCommandsPayload>;
   async listCommands(agentId: string, options?: ListCommandsOptions): Promise<ListCommandsPayload>;
   async listCommands(
@@ -3637,6 +3692,11 @@ export class DaemonClient {
           requestId: msg.payload.requestId,
           resolution: msg.payload.resolution,
         };
+      case "providers_snapshot_update":
+        return {
+          type: "providers_snapshot_update",
+          payload: msg.payload,
+        };
       default:
         return null;
     }

packages/server/src/server/agent/agent-sdk-types.ts

@@ -45,6 +45,8 @@ export type AgentMode = {
   description?: string;
 };
 
+export type ProviderStatus = "ready" | "loading" | "error" | "unavailable";
+
 export type AgentModelDefinition = {
   provider: AgentProvider;
   id: string;
@@ -64,6 +66,15 @@ export type AgentSelectOption = {
   metadata?: AgentMetadata;
 };
 
+export interface ProviderSnapshotEntry {
+  provider: AgentProvider;
+  status: ProviderStatus;
+  error?: string;
+  models?: AgentModelDefinition[];
+  modes?: AgentMode[];
+  fetchedAt?: string;
+}
+
 export type AgentFeatureToggle = {
   type: "toggle";
   id: string;
@@ -468,4 +479,5 @@ export interface AgentClient {
    * Returns true if available, false otherwise.
    */
   isAvailable(): Promise<boolean>;
+  getDiagnostic?(): Promise<{ diagnostic: string }>;
 }

packages/server/src/server/agent/provider-snapshot-manager.test.ts

@@ -0,0 +1,409 @@
+import { describe, expect, test, vi } from "vitest";
+
+import { createTestLogger } from "../../test-utils/test-logger.js";
+import type {
+  AgentClient,
+  AgentMode,
+  AgentModelDefinition,
+  AgentProvider,
+  ProviderSnapshotEntry,
+} from "./agent-sdk-types.js";
+import type { ProviderDefinition } from "./provider-registry.js";
+import { ProviderSnapshotManager } from "./provider-snapshot-manager.js";
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+};
+
+type MockProviderOptions = {
+  provider: AgentProvider;
+  isAvailable?: () => Promise<boolean>;
+  fetchModels?: (cwd?: string) => Promise<AgentModelDefinition[]>;
+  fetchModes?: (cwd?: string) => Promise<AgentMode[]>;
+};
+
+type MockProviderHandle = {
+  definition: ProviderDefinition;
+  isAvailable: ReturnType<typeof vi.fn>;
+  fetchModels: ReturnType<typeof vi.fn>;
+  fetchModes: ReturnType<typeof vi.fn>;
+};
+
+const TEST_CAPABILITIES = {
+  supportsStreaming: false,
+  supportsSessionPersistence: false,
+  supportsDynamicModes: false,
+  supportsMcpServers: false,
+  supportsReasoningStream: false,
+  supportsToolInvocations: false,
+} as const;
+
+describe("ProviderSnapshotManager", () => {
+  test("getSnapshot returns all providers in loading state initially and triggers warmUp", async () => {
+    const codexModels = deferred<AgentModelDefinition[]>();
+    const claudeModels = deferred<AgentModelDefinition[]>();
+    const { registry, handles } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async () => codexModels.promise,
+      }),
+      createMockProvider({
+        provider: "claude",
+        fetchModels: async () => claudeModels.promise,
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    const snapshot = manager.getSnapshot("/tmp/project");
+
+    expect(snapshot).toEqual([
+      { provider: "claude", status: "loading" },
+      { provider: "codex", status: "loading" },
+    ]);
+
+    await vi.waitFor(() => {
+      expect(handles.claude?.isAvailable).toHaveBeenCalledTimes(1);
+      expect(handles.codex?.isAvailable).toHaveBeenCalledTimes(1);
+    });
+
+    manager.destroy();
+    codexModels.resolve([]);
+    claudeModels.resolve([]);
+  });
+
+  test("after warmUp completes, getSnapshot returns ready entries with models", async () => {
+    const { registry } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async () => [createModel("codex", "gpt-5.2")],
+        fetchModes: async () => [createMode("auto")],
+      }),
+      createMockProvider({
+        provider: "claude",
+        fetchModels: async () => [createModel("claude", "sonnet")],
+        fetchModes: async () => [createMode("default")],
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project");
+
+    await vi.waitFor(() => {
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project"), "claude")?.status).toBe("ready");
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project"), "codex")?.status).toBe("ready");
+    });
+
+    const snapshot = manager.getSnapshot("/tmp/project");
+    expect(getProviderEntry(snapshot, "codex")).toMatchObject({
+      provider: "codex",
+      status: "ready",
+      models: [createModel("codex", "gpt-5.2")],
+      modes: [createMode("auto")],
+    });
+    expect(getProviderEntry(snapshot, "claude")).toMatchObject({
+      provider: "claude",
+      status: "ready",
+      models: [createModel("claude", "sonnet")],
+      modes: [createMode("default")],
+    });
+    expect(getProviderEntry(snapshot, "codex")?.fetchedAt).toEqual(expect.any(String));
+
+    manager.destroy();
+  });
+
+  test("provider that fails isAvailable shows as unavailable", async () => {
+    const { registry, handles } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        isAvailable: async () => false,
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project");
+
+    await vi.waitFor(() => {
+      expect(manager.getSnapshot("/tmp/project")).toEqual([
+        { provider: "codex", status: "unavailable" },
+      ]);
+    });
+
+    expect(handles.codex?.fetchModels).not.toHaveBeenCalled();
+    expect(handles.codex?.fetchModes).not.toHaveBeenCalled();
+
+    manager.destroy();
+  });
+
+  test("provider that fails fetchModels shows as error with error message", async () => {
+    const { registry } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async () => {
+          throw new Error("model lookup failed");
+        },
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project");
+
+    await vi.waitFor(() => {
+      expect(manager.getSnapshot("/tmp/project")).toEqual([
+        {
+          provider: "codex",
+          status: "error",
+          error: "model lookup failed",
+        },
+      ]);
+    });
+
+    manager.destroy();
+  });
+
+  test("change event fires for each provider as it resolves", async () => {
+    const codexModels = deferred<AgentModelDefinition[]>();
+    const claudeModels = deferred<AgentModelDefinition[]>();
+    const codexModes = deferred<AgentMode[]>();
+    const claudeModes = deferred<AgentMode[]>();
+    const { registry } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async () => codexModels.promise,
+        fetchModes: async () => codexModes.promise,
+      }),
+      createMockProvider({
+        provider: "claude",
+        fetchModels: async () => claudeModels.promise,
+        fetchModes: async () => claudeModes.promise,
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+    const changes: Array<{ cwd: string; entries: ProviderSnapshotEntry[] }> = [];
+    const listener = (entries: ProviderSnapshotEntry[], cwd: string) => {
+      changes.push({ cwd, entries });
+    };
+    manager.on("change", listener);
+
+    manager.getSnapshot("/tmp/project");
+
+    claudeModels.resolve([createModel("claude", "sonnet")]);
+    claudeModes.resolve([createMode("default")]);
+
+    await vi.waitFor(() => {
+      expect(changes).toHaveLength(1);
+    });
+
+    expect(changes[0]?.cwd).toBe("/tmp/project");
+    expect(getProviderEntry(changes[0]?.entries ?? [], "claude")?.status).toBe("ready");
+    expect(getProviderEntry(changes[0]?.entries ?? [], "codex")?.status).toBe("loading");
+
+    codexModels.resolve([createModel("codex", "gpt-5.2")]);
+    codexModes.resolve([createMode("auto")]);
+
+    await vi.waitFor(() => {
+      expect(changes).toHaveLength(2);
+    });
+
+    expect(getProviderEntry(changes[1]?.entries ?? [], "codex")?.status).toBe("ready");
+    expect(getProviderEntry(changes[1]?.entries ?? [], "claude")?.status).toBe("ready");
+
+    manager.off("change", listener);
+    manager.destroy();
+  });
+
+  test("refresh re-fetches and updates entries", async () => {
+    const codexFetchModels = vi
+      .fn<(options?: { cwd?: string }) => Promise<AgentModelDefinition[]>>()
+      .mockResolvedValueOnce([createModel("codex", "gpt-5.1")])
+      .mockResolvedValueOnce([createModel("codex", "gpt-5.2")]);
+    const { registry } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async (cwd) => codexFetchModels({ cwd }),
+        fetchModes: async () => [createMode("auto")],
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project");
+
+    await vi.waitFor(() => {
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project"), "codex")?.models?.[0]?.id).toBe(
+        "gpt-5.1",
+      );
+    });
+
+    manager.refresh("/tmp/project");
+    expect(manager.getSnapshot("/tmp/project")).toEqual([
+      { provider: "codex", status: "loading" },
+    ]);
+
+    await vi.waitFor(() => {
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project"), "codex")?.models?.[0]?.id).toBe(
+        "gpt-5.2",
+      );
+    });
+
+    expect(codexFetchModels).toHaveBeenCalledTimes(2);
+
+    manager.destroy();
+  });
+
+  test("multiple getSnapshot calls for same cwd do not trigger multiple warmUps", async () => {
+    const codexModels = deferred<AgentModelDefinition[]>();
+    const { registry, handles } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async () => codexModels.promise,
+      }),
+      createMockProvider({
+        provider: "claude",
+        fetchModels: async () => [],
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project");
+    manager.getSnapshot("/tmp/project");
+    manager.getSnapshot("/tmp/project");
+
+    await vi.waitFor(() => {
+      expect(handles.codex?.isAvailable).toHaveBeenCalledTimes(1);
+      expect(handles.codex?.fetchModels).toHaveBeenCalledTimes(1);
+      expect(handles.claude?.isAvailable).toHaveBeenCalledTimes(1);
+      expect(handles.claude?.fetchModels).toHaveBeenCalledTimes(1);
+    });
+
+    codexModels.resolve([createModel("codex", "gpt-5.2")]);
+
+    await vi.waitFor(() => {
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project"), "codex")?.status).toBe("ready");
+    });
+
+    manager.destroy();
+  });
+
+  test("different cwd keys get independent snapshots", async () => {
+    const seenCwds: string[] = [];
+    const { registry } = createRegistry([
+      createMockProvider({
+        provider: "codex",
+        fetchModels: async (cwd) => {
+          seenCwds.push(cwd ?? "__missing__");
+          return [createModel("codex", `model:${cwd}`)];
+        },
+      }),
+    ]);
+    const manager = new ProviderSnapshotManager(registry, createTestLogger());
+
+    manager.getSnapshot("/tmp/project-a");
+    manager.getSnapshot("/tmp/project-b");
+
+    await vi.waitFor(() => {
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project-a"), "codex")?.status).toBe("ready");
+      expect(getProviderEntry(manager.getSnapshot("/tmp/project-b"), "codex")?.status).toBe("ready");
+    });
+
+    expect(getProviderEntry(manager.getSnapshot("/tmp/project-a"), "codex")?.models?.[0]?.id).toBe(
+      "model:/tmp/project-a",
+    );
+    expect(getProviderEntry(manager.getSnapshot("/tmp/project-b"), "codex")?.models?.[0]?.id).toBe(
+      "model:/tmp/project-b",
+    );
+    expect(seenCwds).toEqual(["/tmp/project-a", "/tmp/project-b"]);
+
+    manager.destroy();
+  });
+});
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function createRegistry(handles: MockProviderHandle[]): {
+  registry: Record<AgentProvider, ProviderDefinition>;
+  handles: Record<AgentProvider, MockProviderHandle>;
+} {
+  return {
+    registry: Object.fromEntries(
+      handles.map((handle) => [handle.definition.id, handle.definition]),
+    ) as Record<AgentProvider, ProviderDefinition>,
+    handles: Object.fromEntries(
+      handles.map((handle) => [handle.definition.id, handle]),
+    ) as Record<AgentProvider, MockProviderHandle>,
+  };
+}
+
+function createMockProvider(options: MockProviderOptions): MockProviderHandle {
+  const isAvailable = vi.fn(async () => options.isAvailable?.() ?? true);
+  const fetchModels = vi.fn(async (listOptions?: { cwd?: string }) =>
+    options.fetchModels?.(listOptions?.cwd) ?? [createModel(options.provider, `${options.provider}-default`)],
+  );
+  const fetchModes = vi.fn(async (listOptions?: { cwd?: string }) =>
+    options.fetchModes?.(listOptions?.cwd) ?? [createMode(`${options.provider}-mode`)],
+  );
+
+  const definition: ProviderDefinition = {
+    id: options.provider,
+    label: options.provider,
+    description: `${options.provider} test provider`,
+    defaultModeId: null,
+    modes: [],
+    createClient: () =>
+      ({
+        provider: options.provider,
+        capabilities: TEST_CAPABILITIES,
+        async createSession() {
+          throw new Error("not implemented");
+        },
+        async resumeSession() {
+          throw new Error("not implemented");
+        },
+        async listModels() {
+          return [];
+        },
+        async isAvailable() {
+          return isAvailable();
+        },
+      }) satisfies AgentClient,
+    fetchModels,
+    fetchModes,
+  };
+
+  return {
+    definition,
+    isAvailable,
+    fetchModels,
+    fetchModes,
+  };
+}
+
+function createModel(provider: AgentProvider, id: string): AgentModelDefinition {
+  return {
+    provider,
+    id,
+    label: id,
+  };
+}
+
+function createMode(id: string): AgentMode {
+  return {
+    id,
+    label: id,
+  };
+}
+
+function getProviderEntry(
+  entries: ProviderSnapshotEntry[],
+  provider: AgentProvider,
+): ProviderSnapshotEntry | undefined {
+  return entries.find((entry) => entry.provider === provider);
+}

packages/server/src/server/agent/provider-snapshot-manager.ts

@@ -0,0 +1,217 @@
+import { EventEmitter } from "node:events";
+import { resolve } from "node:path";
+
+import type { Logger } from "pino";
+
+import type {
+  AgentProvider,
+  ProviderSnapshotEntry,
+} from "./agent-sdk-types.js";
+import type { ProviderDefinition } from "./provider-registry.js";
+import { AGENT_PROVIDER_IDS } from "./provider-manifest.js";
+
+const DEFAULT_CWD_KEY = "__default__";
+
+type ProviderSnapshotChangeListener = (
+  entries: ProviderSnapshotEntry[],
+  cwd?: string,
+) => void;
+
+export class ProviderSnapshotManager {
+  private readonly snapshots = new Map<string, Map<AgentProvider, ProviderSnapshotEntry>>();
+  private readonly warmUps = new Map<string, Promise<void>>();
+  private readonly events = new EventEmitter();
+  private destroyed = false;
+
+  constructor(
+    private readonly providerRegistry: Record<AgentProvider, ProviderDefinition>,
+    private readonly logger: Logger,
+  ) {}
+
+  getSnapshot(cwd?: string): ProviderSnapshotEntry[] {
+    const cwdKey = normalizeCwdKey(cwd);
+    const entries = this.snapshots.get(cwdKey);
+    if (!entries) {
+      const loadingEntries = this.createLoadingEntries();
+      this.snapshots.set(cwdKey, loadingEntries);
+      void this.warmUp(cwd);
+      return entriesToArray(loadingEntries);
+    }
+    return entriesToArray(entries);
+  }
+
+  refresh(cwd?: string): void {
+    const cwdKey = normalizeCwdKey(cwd);
+    this.snapshots.set(cwdKey, this.createLoadingEntries());
+    void this.warmUp(cwd);
+  }
+
+  on(event: "change", listener: ProviderSnapshotChangeListener): this {
+    this.events.on(event, listener);
+    return this;
+  }
+
+  off(event: "change", listener: ProviderSnapshotChangeListener): this {
+    this.events.off(event, listener);
+    return this;
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.events.removeAllListeners();
+    this.snapshots.clear();
+    this.warmUps.clear();
+  }
+
+  private createLoadingEntries(): Map<AgentProvider, ProviderSnapshotEntry> {
+    const entries = new Map<AgentProvider, ProviderSnapshotEntry>();
+    for (const provider of this.getProviderIds()) {
+      entries.set(provider, {
+        provider,
+        status: "loading",
+      });
+    }
+    return entries;
+  }
+
+  private async warmUp(cwd?: string): Promise<void> {
+    const cwdKey = normalizeCwdKey(cwd);
+    const inFlight = this.warmUps.get(cwdKey);
+    if (inFlight) {
+      return inFlight;
+    }
+
+    const warmUpPromise = Promise.allSettled(
+      this.getProviderIds().map((provider) => this.refreshProvider(cwdKey, provider, cwd)),
+    ).then(() => undefined);
+
+    this.warmUps.set(cwdKey, warmUpPromise);
+
+    try {
+      await warmUpPromise;
+    } finally {
+      if (this.warmUps.get(cwdKey) === warmUpPromise) {
+        this.warmUps.delete(cwdKey);
+      }
+    }
+  }
+
+  private async refreshProvider(
+    cwdKey: string,
+    provider: AgentProvider,
+    cwd?: string,
+  ): Promise<void> {
+    const definition = this.providerRegistry[provider];
+    if (!definition) {
+      return;
+    }
+
+    const snapshot = this.getOrCreateSnapshot(cwdKey);
+    snapshot.set(provider, {
+      provider,
+      status: "loading",
+    });
+
+    try {
+      const client = definition.createClient(this.logger);
+      const available = await client.isAvailable();
+      if (!available) {
+        snapshot.set(provider, {
+          provider,
+          status: "unavailable",
+        });
+        this.emitChange(cwdKey);
+        return;
+      }
+
+      const [models, modes] = await Promise.all([
+        definition.fetchModels({ cwd }),
+        definition.fetchModes({ cwd }),
+      ]);
+
+      snapshot.set(provider, {
+        provider,
+        status: "ready",
+        models,
+        modes,
+        fetchedAt: new Date().toISOString(),
+      });
+      this.emitChange(cwdKey);
+    } catch (error) {
+      snapshot.set(provider, {
+        provider,
+        status: "error",
+        error: toErrorMessage(error),
+      });
+      this.logger.warn({ err: error, provider, cwd: cwdKey }, "Failed to refresh provider snapshot");
+      this.emitChange(cwdKey);
+    }
+  }
+
+  private emitChange(cwdKey: string): void {
+    if (this.destroyed) {
+      return;
+    }
+    const snapshot = this.snapshots.get(cwdKey);
+    if (!snapshot) {
+      return;
+    }
+    this.events.emit("change", entriesToArray(snapshot), denormalizeCwdKey(cwdKey));
+  }
+
+  private getOrCreateSnapshot(cwdKey: string): Map<AgentProvider, ProviderSnapshotEntry> {
+    const existing = this.snapshots.get(cwdKey);
+    if (existing) {
+      return existing;
+    }
+
+    const created = this.createLoadingEntries();
+    this.snapshots.set(cwdKey, created);
+    return created;
+  }
+
+  private getProviderIds(): AgentProvider[] {
+    return AGENT_PROVIDER_IDS.filter((provider) => this.providerRegistry[provider]);
+  }
+}
+
+function normalizeCwdKey(cwd?: string): string {
+  if (!cwd) {
+    return DEFAULT_CWD_KEY;
+  }
+
+  const trimmed = cwd.trim();
+  if (!trimmed) {
+    return DEFAULT_CWD_KEY;
+  }
+
+  return resolve(trimmed);
+}
+
+function denormalizeCwdKey(cwdKey: string): string | undefined {
+  return cwdKey === DEFAULT_CWD_KEY ? undefined : cwdKey;
+}
+
+function entriesToArray(
+  entries: Map<AgentProvider, ProviderSnapshotEntry>,
+): ProviderSnapshotEntry[] {
+  return Array.from(entries.values(), cloneEntry);
+}
+
+function cloneEntry(entry: ProviderSnapshotEntry): ProviderSnapshotEntry {
+  return {
+    ...entry,
+    models: entry.models?.map((model) => ({ ...model })),
+    modes: entry.modes?.map((mode) => ({ ...mode })),
+  };
+}
+
+function toErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === "string" && error) {
+    return error;
+  }
+  return "Unknown error";
+}

packages/server/src/server/agent/providers/claude-agent.ts

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import { promises } from "node:fs";
@@ -39,6 +39,12 @@ import {
 } from "./claude/claude-models.js";
 import { parsePartialJsonObject } from "./claude/partial-json.js";
 import { ClaudeSidechainTracker } from "./claude/sidechain-tracker.js";
+import {
+  formatDiagnosticStatus,
+  formatProviderDiagnostic,
+  formatProviderDiagnosticError,
+  toDiagnosticErrorMessage,
+} from "./diagnostic-utils.js";
 
 import type {
   AgentCapabilityFlags,
@@ -1086,6 +1092,42 @@ export class ClaudeAgentClient implements AgentClient {
     return true;
   }
 
+  async getDiagnostic(): Promise<{ diagnostic: string }> {
+    try {
+      const resolvedBinary = findExecutable("claude") ?? "not found";
+      const available = await this.isAvailable();
+      const version = resolveClaudeVersion(this.runtimeSettings);
+      let modelsValue = "Not checked";
+      let status = formatDiagnosticStatus(available);
+
+      if (available) {
+        try {
+          const models = await this.listModels();
+          modelsValue = String(models.length);
+        } catch (error) {
+          modelsValue = `Error - ${toDiagnosticErrorMessage(error)}`;
+          status = formatDiagnosticStatus(available, {
+            source: "model fetch",
+            cause: error,
+          });
+        }
+      }
+
+      return {
+        diagnostic: formatProviderDiagnostic("Claude Code", [
+          { label: "Binary", value: resolvedBinary },
+          ...(version ? [{ label: "Version", value: version }] : []),
+          { label: "Models", value: modelsValue },
+          { label: "Status", value: status },
+        ]),
+      };
+    } catch (error) {
+      return {
+        diagnostic: formatProviderDiagnosticError("Claude Code", error),
+      };
+    }
+  }
+
   private assertConfig(config: AgentSessionConfig): ClaudeAgentConfig {
     if (config.provider !== "claude") {
       throw new Error(`ClaudeAgentClient received config for provider '${config.provider}'`);
@@ -1094,6 +1136,31 @@ export class ClaudeAgentClient implements AgentClient {
   }
 }
 
+function resolveClaudeVersion(runtimeSettings?: ProviderRuntimeSettings): string | null {
+  const command = runtimeSettings?.command;
+
+  try {
+    if (command?.mode === "replace") {
+      return execFileSync(command.argv[0]!, [...command.argv.slice(1), "--version"], {
+        encoding: "utf8",
+        timeout: 5_000,
+      }).trim() || null;
+    }
+
+    const executable = findExecutable("claude");
+    if (!executable) {
+      return null;
+    }
+
+    return execFileSync(executable, ["--version"], {
+      encoding: "utf8",
+      timeout: 5_000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 class ClaudeAgentSession implements AgentSession {
   readonly provider: "claude" = "claude";
   readonly capabilities = CLAUDE_CAPABILITIES;

packages/server/src/server/agent/providers/codex-app-server-agent.ts

@@ -52,6 +52,13 @@ import {
 } from "../../../utils/executable.js";
 import { extractCodexTerminalSessionId, nonEmptyString } from "./tool-call-mapper-utils.js";
 import { buildCodexFeatures, codexModelSupportsFastMode } from "./codex-feature-definitions.js";
+import {
+  formatDiagnosticStatus,
+  formatProviderDiagnostic,
+  formatProviderDiagnosticError,
+  resolveBinaryVersion,
+  toDiagnosticErrorMessage,
+} from "./diagnostic-utils.js";
 
 const DEFAULT_TIMEOUT_MS = 14 * 24 * 60 * 60 * 1000;
 const TURN_START_TIMEOUT_MS = 90 * 1000;
@@ -3947,6 +3954,49 @@ export class CodexAppServerAgentClient implements AgentClient {
     }
     return true;
   }
+
+  async getDiagnostic(): Promise<{ diagnostic: string }> {
+    try {
+      const available = await this.isAvailable();
+      const resolvedBinary = findExecutable("codex");
+      const entries: Array<{ label: string; value: string }> = [
+        {
+          label: "Binary",
+          value: resolvedBinary ?? "not found",
+        },
+        { label: "Version", value: resolvedBinary ? resolveBinaryVersion(resolvedBinary) : "unknown" },
+      ];
+      let status = formatDiagnosticStatus(available);
+
+      if (!available) {
+        entries.push({ label: "Models", value: "Not checked" });
+      } else {
+        try {
+          const models = await this.listModels();
+          entries.push({ label: "Models", value: String(models.length) });
+        } catch (error) {
+          entries.push({
+            label: "Models",
+            value: `Error - ${toDiagnosticErrorMessage(error)}`,
+          });
+          status = formatDiagnosticStatus(available, {
+            source: "model fetch",
+            cause: error,
+          });
+        }
+      }
+
+      entries.push({ label: "Status", value: status });
+
+      return {
+        diagnostic: formatProviderDiagnostic("Codex", entries),
+      };
+    } catch (error) {
+      return {
+        diagnostic: formatProviderDiagnosticError("Codex", error),
+      };
+    }
+  }
 }
 
 export const __codexAppServerInternals = {

packages/server/src/server/agent/providers/copilot-acp-agent.ts

@@ -2,7 +2,15 @@ import type { Logger } from "pino";
 
 import type { AgentCapabilityFlags, AgentMode } from "../agent-sdk-types.js";
 import type { ProviderRuntimeSettings } from "../provider-launch-config.js";
+import { findExecutable } from "../../../utils/executable.js";
 import { ACPAgentClient } from "./acp-agent.js";
+import {
+  formatDiagnosticStatus,
+  formatProviderDiagnostic,
+  formatProviderDiagnosticError,
+  resolveBinaryVersion,
+  toDiagnosticErrorMessage,
+} from "./diagnostic-utils.js";
 
 const COPILOT_CAPABILITIES: AgentCapabilityFlags = {
   supportsStreaming: true,
@@ -51,4 +59,53 @@ export class CopilotACPAgentClient extends ACPAgentClient {
   override async isAvailable(): Promise<boolean> {
     return super.isAvailable();
   }
+
+  async getDiagnostic(): Promise<{ diagnostic: string }> {
+    try {
+      const available = await this.isAvailable();
+      const resolvedBinary = findExecutable("copilot");
+      let modelsValue = "Not checked";
+      let status = formatDiagnosticStatus(available);
+
+      if (available) {
+        try {
+          const models = await this.listModels();
+          modelsValue = String(models.length);
+        } catch (error) {
+          modelsValue = `Error - ${toDiagnosticErrorMessage(error)}`;
+          status = formatDiagnosticStatus(available, {
+            source: "model fetch",
+            cause: error,
+          });
+        }
+
+        if (!modelsValue.startsWith("Error -")) {
+          try {
+            await this.listModes();
+          } catch (error) {
+            status = formatDiagnosticStatus(available, {
+              source: "mode fetch",
+              cause: error,
+            });
+          }
+        }
+      }
+
+      return {
+        diagnostic: formatProviderDiagnostic("Copilot", [
+          {
+            label: "Binary",
+            value: resolvedBinary ?? "not found",
+          },
+          { label: "Version", value: resolvedBinary ? resolveBinaryVersion(resolvedBinary) : "unknown" },
+          { label: "Models", value: modelsValue },
+          { label: "Status", value: status },
+        ]),
+      };
+    } catch (error) {
+      return {
+        diagnostic: formatProviderDiagnosticError("Copilot", error),
+      };
+    }
+  }
 }

packages/server/src/server/agent/providers/diagnostic-utils.ts

@@ -0,0 +1,80 @@
+import { execFileSync } from "node:child_process";
+
+import type { ProviderRuntimeSettings } from "../provider-launch-config.js";
+
+type DiagnosticEntry = {
+  label: string;
+  value: string;
+};
+
+export function formatProviderDiagnostic(
+  providerName: string,
+  entries: DiagnosticEntry[],
+): string {
+  return [providerName, ...entries.map((entry) => `  ${entry.label}: ${entry.value}`)].join("\n");
+}
+
+export function formatProviderDiagnosticError(
+  providerName: string,
+  error: unknown,
+): string {
+  return formatProviderDiagnostic(providerName, [
+    {
+      label: "Error",
+      value: error instanceof Error ? error.message : String(error),
+    },
+  ]);
+}
+
+export function formatAvailabilityStatus(available: boolean): string {
+  return available ? "Available" : "Unavailable";
+}
+
+export function formatDiagnosticStatus(
+  available: boolean,
+  error?: { source: string; cause: unknown },
+): string {
+  if (error) {
+    return `Error (${error.source} failed: ${toDiagnosticErrorMessage(error.cause)})`;
+  }
+  return formatAvailabilityStatus(available);
+}
+
+export function toDiagnosticErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === "string" && error.trim().length > 0) {
+    return error;
+  }
+  return "Unknown error";
+}
+
+export function resolveBinaryVersion(binaryPath: string): string {
+  try {
+    return (
+      execFileSync(binaryPath, ["--version"], {
+        encoding: "utf8",
+        timeout: 5_000,
+      }).trim() || "unknown"
+    );
+  } catch {
+    return "unknown";
+  }
+}
+
+export function formatConfiguredCommand(
+  defaultArgv: readonly string[],
+  runtimeSettings?: ProviderRuntimeSettings,
+): string {
+  const command = runtimeSettings?.command;
+  if (!command || command.mode === "default") {
+    return `${defaultArgv.join(" ")} (default)`;
+  }
+
+  if (command.mode === "append") {
+    return [defaultArgv[0], ...(command.args ?? []), ...defaultArgv.slice(1)].join(" ");
+  }
+
+  return command.argv.join(" ");
+}

packages/server/src/server/agent/providers/opencode-agent.ts

@@ -43,6 +43,13 @@ import {
   quoteWindowsCommand,
 } from "../../../utils/executable.js";
 import { mapOpencodeToolCall } from "./opencode/tool-call-mapper.js";
+import {
+  formatDiagnosticStatus,
+  formatProviderDiagnostic,
+  formatProviderDiagnosticError,
+  resolveBinaryVersion,
+  toDiagnosticErrorMessage,
+} from "./diagnostic-utils.js";
 
 const OPENCODE_CAPABILITIES: AgentCapabilityFlags = {
   supportsStreaming: true,
@@ -615,6 +622,63 @@ export class OpenCodeAgentClient implements AgentClient {
     return true;
   }
 
+  async getDiagnostic(): Promise<{ diagnostic: string }> {
+    try {
+      const available = await this.isAvailable();
+      const resolvedBinary = findExecutable("opencode");
+      let serverStatus = "Not running";
+      let modelsValue = "Not checked";
+      let status = formatDiagnosticStatus(available);
+
+      try {
+        const { url } = await this.serverManager.ensureRunning();
+        serverStatus = `Running (${url})`;
+      } catch (error) {
+        serverStatus = `Unavailable (${normalizeTurnFailureError(error)})`;
+      }
+
+      if (available) {
+        try {
+          const models = await this.listModels();
+          modelsValue = String(models.length);
+        } catch (error) {
+          modelsValue = `Error - ${toDiagnosticErrorMessage(error)}`;
+          status = formatDiagnosticStatus(available, {
+            source: "model fetch",
+            cause: error,
+          });
+        }
+
+        if (!modelsValue.startsWith("Error -")) {
+          try {
+            await this.listModes();
+          } catch (error) {
+            status = formatDiagnosticStatus(available, {
+              source: "mode fetch",
+              cause: error,
+            });
+          }
+        }
+      }
+
+      return {
+        diagnostic: formatProviderDiagnostic("OpenCode", [
+          {
+            label: "Binary",
+            value: resolvedBinary ?? "not found",
+          },
+          { label: "Version", value: resolvedBinary ? resolveBinaryVersion(resolvedBinary) : "unknown" },
+          { label: "Server", value: serverStatus },
+          { label: "Models", value: modelsValue },
+          { label: "Status", value: status },
+        ]),
+      };
+    } catch (error) {
+      return {
+        diagnostic: formatProviderDiagnosticError("OpenCode", error),
+      };
+    }
+  }
   private assertConfig(config: AgentSessionConfig): OpenCodeAgentConfig {
     if (config.provider !== "opencode") {
       throw new Error(`OpenCodeAgentClient received config for provider '${config.provider}'`);

packages/server/src/server/agent/providers/pi-acp-agent.ts

@@ -29,12 +29,19 @@ import type {
   AgentFeatureSelect,
 } from "../agent-sdk-types.js";
 import type { ProviderRuntimeSettings } from "../provider-launch-config.js";
-import { isCommandAvailable } from "../../../utils/executable.js";
+import { findExecutable, isCommandAvailable } from "../../../utils/executable.js";
 import {
   ACPAgentClient,
   type ACPToolSnapshot,
   type SessionStateResponse,
 } from "./acp-agent.js";
+import {
+  formatDiagnosticStatus,
+  formatProviderDiagnostic,
+  formatProviderDiagnosticError,
+  resolveBinaryVersion,
+  toDiagnosticErrorMessage,
+} from "./diagnostic-utils.js";
 
 const require = createRequire(import.meta.url);
 const resolvedPiAcpPath = require.resolve("pi-acp");
@@ -329,4 +336,85 @@ export class PiACPAgentClient extends ACPAgentClient {
       existsSync(join(homedir(), ".pi", "agent", "auth.json"))
     );
   }
+
+  async getDiagnostic(): Promise<{ diagnostic: string }> {
+    try {
+      const piCommand = process.env.PI_ACP_PI_COMMAND ?? "pi";
+      const piCliPath = findExecutable(piCommand);
+      const piVersion = piCliPath ? resolveBinaryVersion(piCliPath) : "unknown";
+      const authConfigPath = join(homedir(), ".pi", "agent", "auth.json");
+      const available = await this.isAvailable();
+      let modelsValue = "Not checked";
+      let status = formatDiagnosticStatus(available);
+
+      if (available) {
+        try {
+          const models = await this.listModels();
+          modelsValue = String(models.length);
+        } catch (error) {
+          modelsValue = `Error - ${toDiagnosticErrorMessage(error)}`;
+          status = formatDiagnosticStatus(available, {
+            source: "model fetch",
+            cause: error,
+          });
+        }
+
+        if (!modelsValue.startsWith("Error -")) {
+          try {
+            await this.listModes();
+          } catch (error) {
+            status = formatDiagnosticStatus(available, {
+              source: "mode fetch",
+              cause: error,
+            });
+          }
+        }
+      }
+
+      return {
+        diagnostic: formatProviderDiagnostic("Pi", [
+          {
+            label: "pi-acp module",
+            value: existsSync(resolvedPiAcpPath) ? "found" : "not found",
+          },
+          {
+            label: "Binary",
+            value: piCliPath ?? "not found",
+          },
+          {
+            label: "Version",
+            value: piVersion,
+          },
+          {
+            label: "OPENAI_API_KEY",
+            value: process.env.OPENAI_API_KEY ? "set" : "not set",
+          },
+          {
+            label: "ANTHROPIC_API_KEY",
+            value: process.env.ANTHROPIC_API_KEY ? "set" : "not set",
+          },
+          {
+            label: "OPENROUTER_API_KEY",
+            value: process.env.OPENROUTER_API_KEY ? "set" : "not set",
+          },
+          {
+            label: "Auth config (~/.pi/agent/auth.json)",
+            value: existsSync(authConfigPath) ? "found" : "not found",
+          },
+          {
+            label: "Models",
+            value: modelsValue,
+          },
+          {
+            label: "Status",
+            value: status,
+          },
+        ]),
+      };
+    } catch (error) {
+      return {
+        diagnostic: formatProviderDiagnosticError("Pi", error),
+      };
+    }
+  }
 }

packages/server/src/server/session.ts

@@ -68,6 +68,7 @@ export type AgentMcpTransportFactory = () => Promise<Transport>;
 import { buildProviderRegistry } from "./agent/provider-registry.js";
 import type { AgentProviderRuntimeSettingsMap } from "./agent/provider-launch-config.js";
 import { AgentManager } from "./agent/agent-manager.js";
+import { ProviderSnapshotManager } from "./agent/provider-snapshot-manager.js";
 import type {
   AgentTimelineCursor,
   AgentTimelineFetchDirection,
@@ -101,6 +102,7 @@ import type {
   AgentStreamEvent,
   AgentProvider,
   AgentPersistenceHandle,
+  ProviderSnapshotEntry,
 } from "./agent/agent-sdk-types.js";
 import { AgentStorage, type StoredAgentRecord } from "./agent/agent-storage.js";
 import { isValidAgentProvider, AGENT_PROVIDER_IDS } from "./agent/provider-manifest.js";
@@ -398,6 +400,7 @@ export type SessionOptions = {
   stt: Resolvable<SpeechToTextProvider | null>;
   tts: Resolvable<TextToSpeechProvider | null>;
   terminalManager: TerminalManager | null;
+  providerSnapshotManager?: ProviderSnapshotManager;
   voice?: {
     voiceAgentMcpStdio?: VoiceMcpStdioConfig | null;
     turnDetection?: Resolvable<TurnDetectionProvider | null>;
@@ -594,6 +597,8 @@ export class Session {
   } | null = null;
   private readonly MOBILE_BACKGROUND_STREAM_GRACE_MS = 60_000;
   private readonly terminalManager: TerminalManager | null;
+  private readonly providerSnapshotManager: ProviderSnapshotManager | null;
+  private unsubscribeProviderSnapshotEvents: (() => void) | null = null;
   private readonly subscribedTerminalDirectories = new Set<string>();
   private unsubscribeTerminalsChanged: (() => void) | null = null;
   private terminalExitSubscriptions: Map<string, () => void> = new Map();
@@ -646,6 +651,7 @@ export class Session {
       stt,
       tts,
       terminalManager,
+      providerSnapshotManager,
       voice,
       voiceBridge,
       dictation,
@@ -671,11 +677,32 @@ export class Session {
     this.checkoutDiffManager = checkoutDiffManager;
     this.createAgentMcpTransport = createAgentMcpTransport;
     this.terminalManager = terminalManager;
+    this.providerSnapshotManager = providerSnapshotManager ?? null;
     if (this.terminalManager) {
       this.unsubscribeTerminalsChanged = this.terminalManager.subscribeTerminalsChanged((event) =>
         this.handleTerminalsChanged(event),
       );
     }
+    if (this.providerSnapshotManager) {
+      const handleProviderSnapshotChange = (entries: ProviderSnapshotEntry[], cwd?: string) => {
+        // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
+        const visibleEntries = entries.filter((entry) =>
+          this.isProviderVisibleToClient(entry.provider),
+        );
+        this.emit({
+          type: "providers_snapshot_update",
+          payload: {
+            cwd,
+            entries: visibleEntries,
+            generatedAt: new Date().toISOString(),
+          },
+        });
+      };
+      this.providerSnapshotManager.on("change", handleProviderSnapshotChange);
+      this.unsubscribeProviderSnapshotEvents = () => {
+        this.providerSnapshotManager?.off("change", handleProviderSnapshotChange);
+      };
+    }
     this.voiceAgentMcpStdio = voice?.voiceAgentMcpStdio ?? null;
     this.resolveVoiceTurnDetection = toResolver(voice?.turnDetection ?? null);
     this.registerVoiceSpeakHandler = voiceBridge?.registerVoiceSpeakHandler;
@@ -1751,6 +1778,18 @@ export class Session {
           await this.handleListAvailableProvidersRequest(msg);
           break;
 
+        case "get_providers_snapshot_request":
+          await this.handleGetProvidersSnapshotRequest(msg);
+          break;
+
+        case "refresh_providers_snapshot_request":
+          await this.handleRefreshProvidersSnapshotRequest(msg);
+          break;
+
+        case "provider_diagnostic_request":
+          await this.handleProviderDiagnosticRequest(msg);
+          break;
+
         case "clear_agent_attention":
           await this.handleClearAgentAttention(msg.agentId);
           break;
@@ -3250,6 +3289,73 @@ export class Session {
     }
   }
 
+  private async handleGetProvidersSnapshotRequest(
+    msg: Extract<SessionInboundMessage, { type: "get_providers_snapshot_request" }>,
+  ): Promise<void> {
+    // COMPAT(providersSnapshot): keep legacy provider-list RPCs alongside snapshot flow.
+    const entries = this.providerSnapshotManager
+      ? this.providerSnapshotManager
+          .getSnapshot(msg.cwd ? expandTilde(msg.cwd) : undefined)
+          .filter((entry) => this.isProviderVisibleToClient(entry.provider))
+      : [];
+
+    this.emit({
+      type: "get_providers_snapshot_response",
+      payload: {
+        entries,
+        generatedAt: new Date().toISOString(),
+        requestId: msg.requestId,
+      },
+    });
+  }
+
+  private async handleRefreshProvidersSnapshotRequest(
+    msg: Extract<SessionInboundMessage, { type: "refresh_providers_snapshot_request" }>,
+  ): Promise<void> {
+    this.providerSnapshotManager?.refresh(msg.cwd ? expandTilde(msg.cwd) : undefined);
+    this.emit({
+      type: "refresh_providers_snapshot_response",
+      payload: {
+        acknowledged: true,
+        requestId: msg.requestId,
+      },
+    });
+  }
+
+  private async handleProviderDiagnosticRequest(
+    msg: Extract<SessionInboundMessage, { type: "provider_diagnostic_request" }>,
+  ): Promise<void> {
+    try {
+      const client = this.providerRegistry[msg.provider].createClient(this.sessionLogger);
+      const diagnostic = client.getDiagnostic
+        ? (await client.getDiagnostic()).diagnostic
+        : "No diagnostic available for this provider.";
+      this.emit({
+        type: "provider_diagnostic_response",
+        payload: {
+          provider: msg.provider,
+          diagnostic,
+          requestId: msg.requestId,
+        },
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.sessionLogger.error(
+        { err, provider: msg.provider },
+        `Failed to get provider diagnostic for ${msg.provider}`,
+      );
+      this.emit({
+        type: "rpc_error",
+        payload: {
+          requestId: msg.requestId,
+          requestType: msg.type,
+          error: `Failed to get provider diagnostic: ${err.message}`,
+          code: "provider_diagnostic_failed",
+        },
+      });
+    }
+  }
+
   private assertSafeGitRef(ref: string, label: string): void {
     if (!/^[A-Za-z0-9._/-]+$/.test(ref)) {
       throw new Error(`Invalid ${label}: ${ref}`);
@@ -7014,6 +7120,10 @@ export class Session {
       this.unsubscribeAgentEvents();
       this.unsubscribeAgentEvents = null;
     }
+    if (this.unsubscribeProviderSnapshotEvents) {
+      this.unsubscribeProviderSnapshotEvents();
+      this.unsubscribeProviderSnapshotEvents = null;
+    }
 
     // Abort any ongoing operations
     this.abortController.abort();

packages/server/src/server/websocket-server.ts

@@ -31,6 +31,8 @@ import { isHostAllowed } from "./allowed-hosts.js";
 import { Session, type SessionLifecycleIntent, type SessionRuntimeMetrics } from "./session.js";
 import type { AgentProvider } from "./agent/agent-sdk-types.js";
 import type { AgentProviderRuntimeSettingsMap } from "./agent/provider-launch-config.js";
+import { ProviderSnapshotManager } from "./agent/provider-snapshot-manager.js";
+import { buildProviderRegistry } from "./agent/provider-registry.js";
 import { PushTokenStore } from "./push/token-store.js";
 import { PushService } from "./push/push-service.js";
 import type { SpeechReadinessSnapshot, SpeechService } from "./speech/speech-runtime.js";
@@ -253,6 +255,7 @@ export class VoiceAssistantWebSocketServer {
   private readonly voiceSpeakHandlers = new Map<string, VoiceSpeakHandler>();
   private readonly voiceCallerContexts = new Map<string, VoiceCallerContext>();
   private readonly agentProviderRuntimeSettings: AgentProviderRuntimeSettingsMap | undefined;
+  private readonly providerSnapshotManager: ProviderSnapshotManager;
   private readonly onLifecycleIntent: ((intent: SessionLifecycleIntent) => void) | null;
   private serverCapabilities: ServerCapabilities | undefined;
   private runtimeWindowStartedAt = Date.now();
@@ -343,6 +346,13 @@ export class VoiceAssistantWebSocketServer {
     this.voice = voice ?? null;
     this.dictation = dictation ?? null;
     this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
+    const providerSnapshotLogger = this.logger.child({ module: "provider-snapshot-manager" });
+    this.providerSnapshotManager = new ProviderSnapshotManager(
+      buildProviderRegistry(providerSnapshotLogger, {
+        runtimeSettings: this.agentProviderRuntimeSettings,
+      }),
+      providerSnapshotLogger,
+    );
     this.onLifecycleIntent = onLifecycleIntent ?? null;
     this.serverCapabilities = buildServerCapabilities({
       readiness: this.speech?.getReadiness() ?? null,
@@ -496,6 +506,7 @@ export class VoiceAssistantWebSocketServer {
     }
 
     await Promise.all(cleanupPromises);
+    this.providerSnapshotManager.destroy();
     this.checkoutDiffManager.dispose();
     this.pendingConnections.clear();
     this.sessions.clear();
@@ -646,6 +657,7 @@ export class VoiceAssistantWebSocketServer {
       stt: () => this.speech?.resolveStt() ?? null,
       tts: () => this.speech?.resolveTts() ?? null,
       terminalManager: this.terminalManager,
+      providerSnapshotManager: this.providerSnapshotManager,
       voice: {
         ...(this.voice ?? {}),
         turnDetection: () => this.speech?.resolveTurnDetection() ?? null,
@@ -792,6 +804,10 @@ export class VoiceAssistantWebSocketServer {
       hostname: getHostname(),
       version: this.daemonVersion,
       ...(this.serverCapabilities ? { capabilities: this.serverCapabilities } : {}),
+      features: {
+        // COMPAT(providersSnapshot): keep optional until all clients rely on snapshot flow.
+        providersSnapshot: true,
+      },
     };
   }
 

packages/server/src/shared/messages.ts

@@ -54,6 +54,8 @@ import type {
   AgentPermissionRequest,
   AgentPermissionResponse,
   AgentPersistenceHandle,
+  ProviderSnapshotEntry,
+  ProviderStatus,
   AgentRuntimeInfo,
   AgentTimelineItem,
   ToolCallDetail,
@@ -69,6 +71,13 @@ const AgentModeSchema: z.ZodType<AgentMode> = z.object({
   description: z.string().optional(),
 });
 
+const ProviderStatusSchema: z.ZodType<ProviderStatus> = z.enum([
+  "ready",
+  "loading",
+  "error",
+  "unavailable",
+]);
+
 const AgentSelectOptionSchema = z.object({
   id: z.string(),
   label: z.string(),
@@ -114,6 +123,15 @@ const AgentModelDefinitionSchema: z.ZodType<AgentModelDefinition> = z.object({
   defaultThinkingOptionId: z.string().optional(),
 });
 
+const ProviderSnapshotEntrySchema: z.ZodType<ProviderSnapshotEntry> = z.object({
+  provider: AgentProviderSchema,
+  status: ProviderStatusSchema,
+  error: z.string().optional(),
+  models: z.array(AgentModelDefinitionSchema).optional(),
+  modes: z.array(AgentModeSchema).optional(),
+  fetchedAt: z.string().optional(),
+});
+
 const AgentCapabilityFlagsSchema: z.ZodType<AgentCapabilityFlags> = z.object({
   supportsStreaming: z.boolean(),
   supportsSessionPersistence: z.boolean(),
@@ -772,6 +790,24 @@ export const ListAvailableProvidersRequestMessageSchema = z.object({
   requestId: z.string(),
 });
 
+export const GetProvidersSnapshotRequestMessageSchema = z.object({
+  type: z.literal("get_providers_snapshot_request"),
+  cwd: z.string().optional(),
+  requestId: z.string(),
+});
+
+export const RefreshProvidersSnapshotRequestMessageSchema = z.object({
+  type: z.literal("refresh_providers_snapshot_request"),
+  cwd: z.string().optional(),
+  requestId: z.string(),
+});
+
+export const ProviderDiagnosticRequestMessageSchema = z.object({
+  type: z.literal("provider_diagnostic_request"),
+  provider: AgentProviderSchema,
+  requestId: z.string(),
+});
+
 export const ResumeAgentRequestMessageSchema = z.object({
   type: z.literal("resume_agent_request"),
   handle: AgentPersistenceHandleSchema,
@@ -1275,6 +1311,9 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModesRequestMessageSchema,
   ListProviderFeaturesRequestMessageSchema,
   ListAvailableProvidersRequestMessageSchema,
+  GetProvidersSnapshotRequestMessageSchema,
+  RefreshProvidersSnapshotRequestMessageSchema,
+  ProviderDiagnosticRequestMessageSchema,
   ResumeAgentRequestMessageSchema,
   RefreshAgentRequestMessageSchema,
   CancelAgentRequestMessageSchema,
@@ -1500,6 +1539,12 @@ export const ServerInfoStatusPayloadSchema = z
     hostname: ServerInfoHostnameSchema.optional(),
     version: ServerInfoVersionSchema.optional(),
     capabilities: ServerCapabilitiesFromUnknownSchema,
+    // COMPAT(providersSnapshot): added in v0.1.48, remove gating when all clients use snapshot
+    features: z
+      .object({
+        providersSnapshot: z.boolean().optional(),
+      })
+      .optional(),
   })
   .passthrough()
   .transform((payload) => ({
@@ -2235,6 +2280,45 @@ export const ListAvailableProvidersResponseSchema = z.object({
   }),
 });
 
+// COMPAT(providersSnapshot): added in v0.1.48, remove gating when all clients use snapshot
+export const GetProvidersSnapshotResponseMessageSchema = z.object({
+  type: z.literal("get_providers_snapshot_response"),
+  payload: z.object({
+    entries: z.array(ProviderSnapshotEntrySchema),
+    generatedAt: z.string(),
+    requestId: z.string(),
+  }),
+});
+
+// COMPAT(providersSnapshot): added in v0.1.48, remove gating when all clients use snapshot
+export const ProvidersSnapshotUpdateMessageSchema = z.object({
+  type: z.literal("providers_snapshot_update"),
+  payload: z.object({
+    cwd: z.string().optional(),
+    entries: z.array(ProviderSnapshotEntrySchema),
+    generatedAt: z.string(),
+  }),
+});
+
+// COMPAT(providersSnapshot): added in v0.1.48, remove gating when all clients use snapshot
+export const RefreshProvidersSnapshotResponseMessageSchema = z.object({
+  type: z.literal("refresh_providers_snapshot_response"),
+  payload: z.object({
+    requestId: z.string(),
+    acknowledged: z.boolean(),
+  }),
+});
+
+// COMPAT(providersSnapshot): added in v0.1.48, remove gating when all clients use snapshot
+export const ProviderDiagnosticResponseMessageSchema = z.object({
+  type: z.literal("provider_diagnostic_response"),
+  payload: z.object({
+    provider: AgentProviderSchema,
+    diagnostic: z.string(),
+    requestId: z.string(),
+  }),
+});
+
 const AgentSlashCommandSchema = z.object({
   name: z.string(),
   description: z.string(),
@@ -2428,6 +2512,10 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   ListProviderModesResponseMessageSchema,
   ListProviderFeaturesResponseMessageSchema,
   ListAvailableProvidersResponseSchema,
+  GetProvidersSnapshotResponseMessageSchema,
+  ProvidersSnapshotUpdateMessageSchema,
+  RefreshProvidersSnapshotResponseMessageSchema,
+  ProviderDiagnosticResponseMessageSchema,
   ListCommandsResponseSchema,
   ListTerminalsResponseSchema,
   TerminalsChangedSchema,
@@ -2507,6 +2595,16 @@ export type ListProviderFeaturesResponseMessage = z.infer<
   typeof ListProviderFeaturesResponseMessageSchema
 >;
 export type ListAvailableProvidersResponse = z.infer<typeof ListAvailableProvidersResponseSchema>;
+export type GetProvidersSnapshotResponseMessage = z.infer<
+  typeof GetProvidersSnapshotResponseMessageSchema
+>;
+export type ProvidersSnapshotUpdateMessage = z.infer<typeof ProvidersSnapshotUpdateMessageSchema>;
+export type RefreshProvidersSnapshotResponseMessage = z.infer<
+  typeof RefreshProvidersSnapshotResponseMessageSchema
+>;
+export type ProviderDiagnosticResponseMessage = z.infer<
+  typeof ProviderDiagnosticResponseMessageSchema
+>;
 export type ChatCreateResponse = z.infer<typeof ChatCreateResponseSchema>;
 export type ChatListResponse = z.infer<typeof ChatListResponseSchema>;
 export type ChatInspectResponse = z.infer<typeof ChatInspectResponseSchema>;
@@ -2554,6 +2652,15 @@ export type ListProviderFeaturesRequestMessage = z.infer<
 export type ListAvailableProvidersRequestMessage = z.infer<
   typeof ListAvailableProvidersRequestMessageSchema
 >;
+export type GetProvidersSnapshotRequestMessage = z.infer<
+  typeof GetProvidersSnapshotRequestMessageSchema
+>;
+export type RefreshProvidersSnapshotRequestMessage = z.infer<
+  typeof RefreshProvidersSnapshotRequestMessageSchema
+>;
+export type ProviderDiagnosticRequestMessage = z.infer<
+  typeof ProviderDiagnosticRequestMessageSchema
+>;
 export type ChatCreateRequest = z.infer<typeof ChatCreateRequestSchema>;
 export type ChatListRequest = z.infer<typeof ChatListRequestSchema>;
 export type ChatInspectRequest = z.infer<typeof ChatInspectRequestSchema>;