PersonaBot model presets and per-Session model routing #488

Problem Statement

A Human cannot currently choose a PersonaBot's provider, model, or reasoning effort as a coherent plan for its Orchestrator and delegated work. One deployment-wide model and a legacy per-Bot model string cannot express a fixed Orchestrator route, a bounded Assignment choice set, or reusable “high intelligence” and “economy” setups. The Human also cannot tell which route a Bot will actually use after switching a setup.

Solution

Let the Human create deployment-local Model Presets, each with one exact Orchestrator provider/model/effort and an Assignment set of exact routes, allowed efforts, per-route default efforts, and one default Assignment route. Applying a preset copies a PersonaBot Model Plan snapshot; the Human can switch presets quickly or customize one Bot without changing the reusable template or other Bots. The Profile shows the effective selection, and Host execution validates it at the next applicable DSH Session request. A missing route stops visibly for Human repair instead of silently falling back.

User Stories

1. As a Human, I want to create a named Model Preset, so that I can reuse a high-intelligence or economy setup.
2. As a Human, I want to choose the Orchestrator's exact provider, model, and reasoning effort, so that its routine conversations have a predictable route.
3. As a Human, I want to give Assignments several exact provider/model choices, so that the Orchestrator can choose a suitable route for each task.
4. As a Human, I want to define allowed efforts and a default effort for every Assignment model, so that the Orchestrator stays within my chosen range.
5. As a Human, I want to designate one default Assignment model and effort, so that omitted choices remain deterministic.
6. As a Human, I want to apply the same preset to several PersonaBots, so that setup does not require repeated entry.
7. As a Human, I want each application to create an independent Bot snapshot, so that later template edits cannot silently change an existing Bot.
8. As a Human, I want to edit a reusable preset, so that future applications use the revised setup.
9. As a Human, I want a compact preset switch in the PersonaBot Profile, so that I can move a Bot between familiar setups quickly.
10. As a Human, I want detailed model-plan editing in a lower Profile section or modal beneath activity charts, so that routine Profile reading stays uncluttered.
11. As a Human, I want to change one Bot's Orchestrator route without editing the shared template, so that this Bot becomes a custom snapshot.
12. As a Human, I want the Profile to show the Bot's effective route and plan revision, so that I can verify what the next eligible request will use.
13. As a Human, I want a change made during an Orchestrator Turn to begin with the next Turn's first model request, so that one in-progress Turn remains coherent.
14. As a Human, I want existing Assignments to keep their current routes when I apply a new preset, so that running work does not switch models unexpectedly.
15. As a Human, I want new Assignments to use the current default unless a permitted choice is supplied, so that new work follows the latest Bot plan.
16. As an Orchestrator, I want to choose an allowed route and effort when creating an Assignment, so that I can match the task's needs to the Human's limits.
17. As an Orchestrator, I want to switch an existing Assignment to another currently allowed route for its next request, so that I can adapt work without restarting it.
18. As a Human, I want disallowed Assignment selections to fail clearly, so that the Orchestrator cannot exceed my current plan.
19. As an Orchestrator, I want a new DSH Subagent to inherit its parent's allowed model and effort by default, so that ordinary delegation is consistent.
20. As an Orchestrator, I want a new Subagent of an old Assignment on an excluded route to use the current Assignment default and tell me what it selected, so that a preset switch does not authorize fresh work on an excluded model.
21. As a Human, I want unavailable providers, models, efforts, or credentials to stop the request and identify the choice to repair, so that no other provider is used without my decision.
22. As a Human upgrading an existing profile, I want an unambiguous legacy model choice migrated automatically, so that my Bot continues working.
23. As a Human upgrading an ambiguous legacy choice, I want the Bot to wait for my route selection, so that migration never guesses the provider.
24. As a Human, I want Model Presets and Bot plans in an identity-preserving Profile Backup, so that I can restore my own deployment configuration.
25. As a Human sharing a PersonaBot, I want its Export and SoulSnapshot to omit model bindings, so that recipients use their own providers and budgets.
26. As a Human, I want model configuration to remain distinct from a DSH Agent preset for tools and prompts, so that the two settings do not overwrite each other.

Implementation Decisions

• The PersonaBot module owns the application-defined Model Plan and its revision. A separate deployment-local template catalog owns reusable Model Presets. Applying a template copies its values into the Bot plan; no live reference or automatic synchronization remains.
• A route is identified by exact provider and model; effort is an explicit part of the effective choice. The Orchestrator has one route and effort. Each Assignment route carries an allowed effort set and a default effort, and the plan identifies one default Assignment route.
• Human edits to a Bot plan create a custom snapshot. Template edits affect future applications only. The Profile's quick switch and detailed editor issue commands through the existing Host bridge and read back the authoritative effective plan.
• The Host validates choices at the execution boundary using trusted PersonaBot and Session ownership. The DSH Session remains authoritative for execution and its actual model calls. Bot-scoped selection must not silently rewrite the deployment-wide DSH model default.
• Applying a plan does not interrupt a running Orchestrator Turn. The new Orchestrator route takes effect at the first model request of its next Turn. Existing Assignments retain their selected routes, including previously allowed routes now excluded, until an explicit switch; an explicit switch uses the current Bot plan and affects the next request.
• A new Assignment with no explicit choice receives the current plan default. Explicit creation and later switches must satisfy the current exact route and effort allowlist.
• A new DSH Subagent inherits its parent's route and effort only while that combination is allowed by the current Assignment set. An explicit choice is checked against the same set. When a retained parent uses a now-excluded route, the new child uses the current Assignment default and reports the effective route to its parent; an unavailable default fails creation.
• An unavailable route, unsupported effort, or invalid credential produces a repairable Human-facing failure. There is no silent model or provider fallback.
• Legacy single-model configuration migrates when its provider resolves uniquely. Ambiguous or unavailable legacy values leave the Bot requiring Human selection before a new model request. The existing DSH Agent preset field keeps its tools-and-prompt meaning.
• Model Presets and Bot plans are deployment-local operational configuration included in identity-preserving Profile Backup. PersonaBot Export and SoulSnapshot omit them and never contain provider credentials (ADR-0027, ADR-0093).
• Delivery uses vertical slices: first apply one preset in Profile, save its revision, run a real Orchestrator request on the selected route, and display the effective choice; then expand to Assignment choices and switches, then DSH Subagents, migration, and portability. Every UI slice includes a screenshot and operable Human QA state.

Testing Decisions

• Test observable results through the highest existing seam: a Profile command travels through the Host bridge, the effective plan is read back, and a real DSH Session makes a request on the selected provider/model/effort. Do not make private storage shape the acceptance criterion.
• Test the PersonaBot plan command/query, Assignment creation and switching, DSH adapter route application, and Profile rendering through existing Host bridge and Client interaction seams. Follow existing bridge-method, DSH adapter, Assignment collaboration, and PersonaBot Profile tests.
• Verify a live Orchestrator Turn boundary, omitted Assignment choice, allowed and rejected choices, retained Assignment after preset switch, next-request switch, Subagent inheritance and excluded-parent default, unavailable-route repair, and ambiguous migration. Assert the externally visible effective route and failure, not internal helper calls.
• Use an isolated, verified DSH instance for each cross-layer slice. Provide the Human a Bot and Session state they can operate, including a real model reply and the visible Profile selection; capture screenshots for UI PRs.

Out of Scope

• Automatic synchronization of previously applied Bot plans when a template changes.
• Silent fallback to another provider or a deployment-wide default when a chosen route fails.
• Provider credential management, pricing, spending caps, or automatic cost optimization.
• Putting model bindings into PersonaBot Export, SoulSnapshot, or Memory.
• Replacing the DSH Agent preset mechanism for prompts and tools.
• Per-model token accounting and retained statistics, which are specified in Usage read model / Typert remote / Profile contract #39.

Further Notes

• ADR-0093 records snapshot and per-Session routing authority; ADR-0027 preserves the local-only export boundary. Usage read model / Typert remote / Profile contract #39 specifies observed model usage, which must remain separate from allowed model configuration.
• The first production slice must be independently reviewable before expanding sibling paths. PR Document PersonaBot model presets and retained model usage #489 merged the design vocabulary and architecture; this issue remains open until the runtime and Human QA are complete.