create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/docs/walle-session-model-catalog.md

@@ -0,0 +1,90 @@
+# 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.

package/template/claude-task-manager/docs/walle-session-model-preferences.md

@@ -55,9 +55,10 @@ CREATE TABLE session_model_preferences (
 );
 ```
 
-The source-of-truth columns are `ctm_session_id`, `provider_type`, `model_id`,
-and optional `registry_id`. `provider_id` is kept for exact provider-route
-diagnostics when a provider type has multiple routes.
+The source-of-truth columns are `ctm_session_id`, `provider_type`, and
+`model_id`. `registry_id` and `provider_id` are diagnostic fields for exact
+provider-route debugging; normal session picks leave them empty so provider
+route policy remains owned by AI Providers.
 
 ## Resolution Order
 
@@ -74,7 +75,8 @@ the user explicitly opts into fallback.
 
 ## Events
 
-The Wall-E model picker emits a session-scoped `model-change` message:
+The Wall-E model picker emits a session-scoped `model-change` message with a
+provider-native model id:
 
 ```json
 {
@@ -83,7 +85,8 @@ The Wall-E model picker emits a session-scoped `model-change` message:
   "agent_type": "walle",
   "model_id": "kimi-k2.6",
   "model_provider": "moonshot",
-  "model_registry_id": "moonshot-default:kimi-k2.6",
+  "model_registry_id": "",
+  "model_route_mode": "policy",
   "scope": "session"
 }
 ```
@@ -92,6 +95,11 @@ The server validates and persists the preference, updates only that in-memory
 session, refreshes the startup restore hint, and broadcasts `walle-model` to the
 affected session clients.
 
+`model_route_mode: "policy"` means Wall-E resolves the actual provider route at
+runtime from AI Providers configuration. For example, a Claude model selected in
+a session will still use the configured Anthropic route policy, including
+Portkey, without exposing direct-vs-gateway as a session-level choice.
+
 ## Invariants
 
 - Changing the model in Wall-E session A never updates Wall-E brain keys
@@ -110,7 +118,8 @@ affected session clients.
 Coverage should include:
 
 - DB preference upsert/read/delete with cascade behavior.
-- Wall-E picker sends provider-native model id plus provider type.
+- Wall-E picker sends provider-native model id plus provider type in policy
+  route mode.
 - A manual selection persists in CTM and is reused on the next prompt.
 - Restored Wall-E sessions hydrate provider/model from
   `session_model_preferences`, not only `startup_tasks`.