# Wall-E Session Model Catalog

## Product Boundary

Wall-E sessions choose models. The AI Providers page owns provider setup, credentials, route policy, and route health.

That means a session picker should show user-facing model families such as Claude, GPT, DeepSeek, Kimi, Gemini, and local models. It should not ask the user to choose implementation routes such as direct Anthropic versus Anthropic through Portkey. Route choice is resolved by the provider configuration already selected in AI Providers.

## Data Flow

```
Wall-E brain model_providers + model_registry
  -> Wall-E /api/models/coding-catalog
  -> CTM Wall-E session model picker
  -> model-change { model_id, model_provider, model_route_mode: "policy" }
  -> Wall-E chat resolveModelSelection(model_id, model_provider)
  -> AI Provider route policy picks the provider instance
```

The old `/api/models/coding-availability` endpoint remains a live probe endpoint. It is not the session picker source of truth because a provider can fail a list-model probe while still being configured in the registry. The catalog endpoint is registry-first and can optionally merge live health.

## Canonical Model Rows

`/api/models/coding-catalog` collapses duplicate configured routes into one session row keyed by:

```
provider_type + canonical_model_id
```

Examples:

- `anthropic-default:claude-sonnet-4-6`
- `anthropic-portkey-prod:claude-sonnet-4-6`
- `anthropic-portkey-catalog:@anthropic/claude-sonnet-4-6`

All become one row:

```
Anthropic / claude-sonnet-4-6
```

The row includes route metadata for diagnostics:

- `route_mode: "policy"`
- `route_policy: "portkey" | "direct" | "auto"`
- `route_provider_id`
- `route_connection_kind`
- `preferred_registry_id`
- `routes[]`

The desktop and phone session pickers display only the model and a compact non-editable route hint. The route details remain owned by AI Providers.

## Selection Contract

Normal session selection sends policy-mode model identity:

```json
{
  "type": "model-change",
  "agent_type": "walle",
  "model_id": "claude-sonnet-4-6",
  "model_provider": "anthropic",
  "model_registry_id": "",
  "model_route_mode": "policy",
  "scope": "session",
  "pinned": true
}
```

This lets Wall-E resolve the configured provider route at runtime. If AI Providers says Anthropic should route through Portkey, the session uses Portkey without exposing that choice as a session-level control.

Exact registry route selection should be reserved for advanced diagnostics, not the default session picker.

## Invariants

- A configured model must not disappear from sessions only because a live list-model probe fails.
- One user-facing model appears once even if multiple provider instances can serve it.
- Session model changes are scoped to that CTM session and must not mutate global Wall-E defaults.
- Provider route health problems should be shown as route metadata and fixed in AI Providers.
- The picker may group by actual model provider brand, for example GPT under OpenAI and Claude under Anthropic.

## Tests

Coverage should verify:

- Duplicate direct, Portkey, and Portkey-catalog registry rows collapse into one canonical model row.
- The preferred route follows provider route policy while the UI still sends policy-mode model identity.
- Catalog rows are visible without live availability.
- The session picker sends bare provider-native `model_id` and `model_provider`, not a provider-instance registry ID.
- The phone model picker uses the same catalog endpoint and policy-mode payload as desktop.
