Expose a cached high-level model and agent-configuration discovery API

Problem

AgentOS has no high-level, reusable way to discover an agent's models and configuration surface.

The current actor action probe_agent_config in crates/agentos-actor-plugin/src/actions/session.rs creates a complete temporary ACP session, reads configOptions, and calls the fire-and-forget vm.close_session. It does not await adapter-process teardown and returns only raw configuration options.

Products such as GigaCode consequently implement their own:

• Background catalog refresh
• Probe serialization and concurrency limits
• Retry actors/sessions
• Cached and default catalogs
• Per-harness configuration preparation
• Package/configuration invalidation policy
• Startup progress and failure reporting

Cold concurrent probes were also materially slower than serialized probes because adapter startup and package I/O contended with each other.

Proposed API

Expose a high-level AgentOS discovery operation, conceptually:

interface AgentCatalog {
  agentInfo?: AgentInfo
  capabilities?: AgentCapabilities
  configOptions: SessionConfigOption[]
  models: AgentModel[]
  defaultModel?: string
  modes?: SessionModeState
}

discoverAgentCatalog(agentType, options?): Promise<AgentCatalog>

The exact representation can preserve raw ACP configuration options while also supplying a normalized model/default-model view derived from stable ACP model selectors.

Required semantics

• AgentOS owns the complete temporary-session lifecycle.
• Always await session and adapter-process teardown before completing the probe.
• Coalesce concurrent identical discovery requests into one probe.
• Cache by agent package/artifact identity plus relevant runtime/configuration identity.
• Never store or expose raw credential values in cache keys or diagnostics.
• Invalidate on package upgrades and relevant configuration/model-provider changes.
• Support explicit refresh and a bounded cache policy suitable for daemon startup.
• Do not poison a good cached catalog when refresh fails.
• Return structured probe/bootstrap errors with the failing ACP phase.
• A failed or timed-out probe must not leave sessions, processes, event pumps, descriptors, or VM resources behind.
• Keep Rust, TypeScript, and actor-backed behavior consistent.
• Allow callers to format provider-specific HTTP responses without repeating ACP probing logic.

Acceptance tests

• A first discovery call creates one temporary session and returns agent info, capabilities, config options, normalized models, and the default model.
• A second identical call is served from cache without starting an adapter.
• Concurrent identical calls coalesce into one adapter/session startup.
• Package or relevant configuration changes invalidate the cache.
• Explicit refresh replaces the cached catalog only after successful discovery.
• Failed initialization, session/new, and teardown return distinct structured errors.
• Every success, failure, and timeout leaves zero temporary ACP sessions/processes.
• Claude, Pi, OpenCode, and Codex use the same discovery contract.

Outcome

Clients should be able to request an agent catalog without building their own disposable-session orchestration, retries, process cleanup, or cache layer.

Start by reading crates/agentos-actor-plugin/src/actions/session.rs and the probe_agent_config action to understand the existing temporary-session lifecycle. Map the Rust, TypeScript, and actor-backed entry points involved before defining the shared discovery contract. Done means the acceptance tests pass for catalog results, caching and coalescing, invalidation, structured errors, and zero leaked resources.