#6541 feat(desktop,host-service): discover agent capabilities at runtime

What & why

Superset can launch configurable agent commands, but its model and trait pickers rely primarily on metadata shipped with the app. They cannot tell whether a configured executable is present or whether the installed CLI exposes a different, account-specific model catalog.

This PR makes the host service the source of truth for agent capabilities. It discovers availability and model metadata at runtime where the CLI supports it, persists a revisioned last-known-good snapshot, drives the desktop pickers from that snapshot, and validates the final selection again immediately before launch. Agents without runtime discovery keep their curated fallback metadata.

Problem

• Configured agents remained selectable when their executable was unavailable.
• Model pickers could not reflect the catalog exposed to the installed and authenticated CLI.
• Reasoning effort, mode, service tier, and context-window options were not represented by one shared capability contract.

Root cause

There was no host-owned capability source connecting agent configuration, renderer selection, and launch validation. The renderer combined configured agent rows with static model metadata, while launch entry points independently converted selected values into CLI arguments.

That left four missing pieces:

1. bounded, agent-specific discovery on the host;
2. a validated and revisioned snapshot of discovery results;
3. a renderer contract that distinguishes runtime inventory from curated fallback data; and
4. a shared host-side launch preflight that rejects stale or unsupported selections.

Fix

1. Discover capabilities on the host

• Adds bounded subprocess probes with a 4-second timeout, a 1 MB output limit, terminal-compatible environment construction, executable resolution, cancellation, and process-tree cleanup.
• Discovers runtime model inventories from Antigravity, Copilot, Codex, Cursor Agent, Grok, Kimi Code, OpenCode, and Pi using each provider's supported local interface.
• Separately records executable, authentication, version, inventory-source, and probe-health information so one failure does not collapse every capability into a single status.
• Sanitizes diagnostics before they cross the host boundary.
• Retains curated model catalogs as explicit fallback data for agents that do not expose a runtime inventory.

2. Persist revisioned snapshots

• Adds host_agent_capability_snapshots and a capability revision on agent configs.
• Validates and bounds persisted inventories before storage, including model counts, string lengths, unique IDs, default values, and serialized size.
• Hydrates the picker from persisted snapshots without waiting for every CLI probe, then performs one explicit refresh per host and renderer lifetime.
• Cancels an in-flight cold snapshot read before publishing refreshed data so an older response cannot overwrite the new result.
• Invalidates stale snapshots when command, arguments, or environment configuration changes.
• Coalesces concurrent refreshes by agent and revision, limits probe concurrency, and prevents obsolete results from overwriting newer configuration.
• Preserves the last valid inventory during transient failures while still exposing the latest health result.
• Stops displaying inventory data after 7 days and prunes retained snapshots after 30 days.

3. Validate every launch against the same contract

• Treats a runtime-discovered inventory as authoritative and combines persisted fallback inventory with the curated catalog when runtime discovery is unavailable.
• Validates explicit model, reasoning effort, mode, service tier, and context-window selections before command construction.
• Carries the agent, preset, and config revision through validation, then asserts that they are still current immediately before launch.
• Returns a precondition failure when configuration or selection changes race with launch.
• Applies the same validation path to direct agent terminals, workspace/session creation, and preset execution.

4. Drive the desktop UI from discovered capabilities

• Hides an agent only when the host has confirmed that its executable is missing; unknown or temporarily unhealthy probes remain visible.
• Populates model choices from runtime snapshots and clearly groups current and legacy fallback models.
• Unifies reasoning effort, mode, service tier, and context-window controls in the traits picker.
• Resolves Cursor variant families to their concrete launch model and traits.
• Sanitizes and persists preferences per agent and model, including route changes and modal remounts.
• Adds the Antigravity built-in preset and icon.

Data flow

flowchart LR
  A[Host agent config] --> B[Bounded capability probe]
  B --> C[Validated revisioned snapshot]
  G[Curated fallback metadata] --> C
  C --> D[Agent, model, and trait pickers]
  D --> E[Host launch preflight]
  A --> E
  E --> F[Terminal, workspace, or preset launch]

Behavior notes

• Missing executables are filtered only after a conclusive host result; an auth prompt, timeout, or parse failure does not make an agent disappear.
• Runtime model inventories are authoritative for the config revision that produced them.
• Curated catalogs remain available as fallback and compatibility data.
• Omitting an explicit model still delegates to the agent's default behavior.
• Existing custom agent configs remain supported even when they have no discoverable model inventory.

Review guide

The change is easiest to review in this order:

1. shared capability and launch-selection contracts in packages/shared/src/agent-models.ts;
2. discovery, persistence, and refresh coordination in packages/host-service/src/agent-capabilities/;
3. config invalidation and tRPC launch preflight in the host-service routers;
4. renderer hydration and availability in useV2AgentChoices; and
5. model ordering, trait selection, Cursor variants, and preference persistence in the desktop components and hooks.

Demo

https://github.com/user-attachments/assets/41fee21b-55db-4459-b3c9-e4fe0e8091f7

The recording demonstrates switching among installed agents, loading provider-specific runtime models, selecting Codex reasoning and service-tier traits.

How I tested it

Automated validation

• bun install --frozen-lockfile
• bun run lint:fix
• bun run lint
• bun run typecheck — 38/38 workspace tasks passed
• Focused capability, launch, and renderer test matrix — 255 tests across 16 files passed
• bun run build — desktop production build and AppImage packaging passed, including native runtime validation
• git diff --check

The focused matrix covers discovery parsers, executable resolution, timeouts and cleanup, snapshot schema and persistence, refresh concurrency and race protection, agent-config lifecycle changes, all launch entry points, renderer cache races, availability filtering, model ordering, Cursor variants, traits, and preference persistence.

Manual desktop verification

Verified against the local desktop app through the real renderer and host API:

1. Opened the New Workspace agent picker and confirmed that known-missing agents were excluded.
2. Switched to Codex and confirmed that the runtime inventory exposed GPT-5.6 Sol, Terra, Luna, GPT-5.5, GPT-5.3 Codex Spark, and Daybreak Blue, with legacy fallback models grouped separately.
3. Selected GPT-5.6 Terra and confirmed the available reasoning levels and Standard/Fast service tiers.
4. Selected High reasoning and Fast service tier.
5. Navigated to Workspaces, reopened New Workspace, and confirmed that Codex / Terra / High / Fast persisted.
6. Confirmed that the renderer reported no console errors during the flow.
7. Restored the original local agent preferences after verification.

Full monorepo test run

bun run test was also run, but the fully concurrent monorepo run did not complete green. It reported two isolation/load-sensitive failures outside the new capability assertions:

• @superset/agent-setup: the disabled-hooks suite observed another concurrent test's process-global SUPERSET_HOME_DIR; the file passes 4/4 in isolation.
• @superset/host-service: two existing agent-config tests exceeded their 5-second timeout under full-suite load; the focused agent-config suite passes.

The new discovery, snapshot, launch-contract, and renderer suites passed. This note intentionally does not claim that the root test command was green.

Checklist

• PR title follows conventional commits (feat(desktop,host-service): discover agent capabilities at runtime)
• bun run lint and bun run typecheck pass
• "Allow edits from maintainers" is enabled after the fork PR is created

---

Summary by cubic

Discovers agent executables, auth, versions, and model catalogs at runtime on the host and makes that snapshot the source of truth for desktop pickers and launches. Previously the UI relied on app-shipped metadata; now the host hides only conclusively missing agents, requires selecting an available agent, and hardens pre-launch validation of model and traits (effort, mode, speed, context window).

• Migrate the host: adds host_agent_capability_snapshots and host_agent_configs.capabilityRevision (migration tag 0024). packages/host-service now depends on @github/copilot-sdk.
• No renderer migration required. Desktop hydrates from persisted snapshots and refreshes once per active host per session; curated catalogs remain as fallback while probes run.
• Editing an agent’s command, args, or env bumps its capability revision and invalidates stale snapshots automatically; renderer query invalidation handles same-session updates.
• Ensure installed CLIs are present and authenticated to populate runtime catalogs; agents without discovery continue to use curated fallback metadata.

Summary by CodeRabbit

Summary by CodeRabbit

• New Features

  • Added runtime detection of installed agents, models, and supported launch options.
  • Added workspace controls for model, effort, mode, speed, and context-window settings.
  • Added Antigravity agent support and icon.
  • Added model grouping, provider labels, sorting, and variant selection.
  • Added capability-aware launch validation and command resolution.

• Bug Fixes

  • Improved fallback behavior for unavailable saved selections.
  • Prevented retired models and unsupported options from launching workspaces.
  • Improved capability refresh and configuration update handling.