fix(agents): enforce exact profile model identity (#3473)
Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# ADR-2026-08-15: Let the Executor Own Model Selection
|
||||
|
||||
**Status:** accepted
|
||||
**Status:** superseded by 2026-09-06-exact-profile-model-identity
|
||||
**Date:** 2026-08-15
|
||||
**Area:** backend, frontend, protocol, persistence
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
# ADR-2026-09-06-exact-profile-model-identity: Enforce Exact Profile Model Identity
|
||||
|
||||
**Status:** superseded by 2026-09-15-explicit-profile-model-strictness
|
||||
**Date:** 2026-09-06
|
||||
**Area:** backend, frontend, protocol, persistence, workflow
|
||||
|
||||
See [the per-profile opt-in amendment](2026-09-15-explicit-profile-model-strictness.md).
|
||||
The original decision below is historical; its implicit default is superseded.
|
||||
|
||||
## Context
|
||||
|
||||
An executor catalog remains authoritative for whether a model can be selected,
|
||||
but allowing its default after an exact profile's model is absent changes the
|
||||
user's chosen runtime identity and cost policy before the first prompt.
|
||||
|
||||
## Decision
|
||||
|
||||
A profile with a non-empty model, `auto_fallback = false`, and no
|
||||
`fallback_model` is exact. Its configured model must be advertised and applied
|
||||
before inference. If that cannot be attested, the session fails before a
|
||||
prompt, tool call, or agent output.
|
||||
|
||||
Kandev never sends `SetModel` for an unadvertised model. An advertised explicit
|
||||
fallback is the only authorized alternate model when auto fallback is off.
|
||||
`auto_fallback = true` explicitly authorizes continuation on the executor
|
||||
default and keeps its durable warning behavior. This same decision applies on
|
||||
initial launch, context reset, and fresh workspace rebind.
|
||||
|
||||
## Consequences
|
||||
|
||||
Exact profiles can fail when an executor, account, or pinned runtime does not
|
||||
advertise their configured model. The failure records sanitized requested,
|
||||
effective-when-known, and stable mismatch-reason evidence. Existing workflow
|
||||
profile precedence and intentional same-session runtime overrides remain
|
||||
unchanged.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
1. Continue on the executor default for every catalog mismatch. Rejected
|
||||
because it silently substitutes the chosen model identity.
|
||||
2. Send an unadvertised model selection request. Rejected because the executor
|
||||
catalog is still the availability authority.
|
||||
3. Rewrite the saved profile from an executor observation. Rejected because a
|
||||
transient executor/account state must not mutate the user's profile.
|
||||
@@ -1,9 +1,12 @@
|
||||
# ADR-2026-09-07: Resolve Only One Advertised Model Variation
|
||||
|
||||
**Status:** proposed
|
||||
**Status:** superseded by 2026-09-15-explicit-profile-model-strictness
|
||||
**Date:** 2026-09-07
|
||||
**Area:** backend, frontend, protocol
|
||||
**Amends:** `2026-08-15-executor-authoritative-model-selection`
|
||||
|
||||
The historical rejection below is superseded by the
|
||||
[compatible-only variation rule](2026-09-15-explicit-profile-model-strictness.md).
|
||||
Explicit strict profiles continue to reject inferred variations.
|
||||
|
||||
## Context
|
||||
|
||||
@@ -20,55 +23,25 @@ Variation text is provider-owned. Kandev cannot safely rank `270k`, `1m`,
|
||||
`fast`, or future labels. Catalog order and the current-model marker do not
|
||||
express user intent.
|
||||
|
||||
## Decision
|
||||
## Rejection
|
||||
|
||||
Kandev recognizes a model variation only by a narrow bracketed ID shape. A bare
|
||||
requested ID `x` matches an advertised ID `x[v]` when `v` is non-empty and
|
||||
contains no bracket. Matching is exact and case-sensitive. Kandev treats `v` as
|
||||
opaque text.
|
||||
This proposal was not adopted. It would have inferred a bracketed advertised
|
||||
model from a bare profile model and treated that inferred ID as an authorized
|
||||
selection. That conflicts with the accepted exact-profile boundary: an
|
||||
inferred ID is a different runtime identity from the configured model.
|
||||
|
||||
For profiles with `auto_fallback = false`, the executor-authoritative resolution
|
||||
order is:
|
||||
No variation-matching algorithm, inferred-selection outcome, warning reason,
|
||||
or launch, reset, or workspace-rebind behavior was adopted from this proposal.
|
||||
The accepted policy is recorded exclusively in
|
||||
[Enforce Exact Profile Model Identity](2026-09-06-exact-profile-model-identity.md).
|
||||
|
||||
1. Exact requested model.
|
||||
2. Advertised explicit fallback from the profile.
|
||||
3. One distinct advertised variation of the requested bare model.
|
||||
4. Provider current or default model, with no speculative model-selection call.
|
||||
## Consequences of rejection
|
||||
|
||||
Kandev applies step 3 only when exactly one distinct candidate exists. Zero or
|
||||
multiple candidates produce no inferred selection. An unadvertised explicit
|
||||
fallback does not block step 3.
|
||||
|
||||
A requested ID that contains a bracket is an exact ID only. Kandev does not
|
||||
infer another variation from it.
|
||||
|
||||
Profiles with `auto_fallback = true` retain the legacy path when the requested
|
||||
model is absent. Kandev ignores the configured explicit fallback, does not
|
||||
infer a variation, and continues with the provider current or default model.
|
||||
Apply errors for an advertised model remain best-effort in that mode.
|
||||
|
||||
The lifecycle stores `unique_variation` as the decision outcome and
|
||||
`unique_variation_applied` as the warning reason. The effective model contains
|
||||
the advertised variation. The explicit fallback field keeps its existing
|
||||
meaning and stays empty when Kandev infers a variation.
|
||||
|
||||
The saved profile model does not change. The rule runs for initial launch,
|
||||
context reset, and workspace rebind. The executor catalog remains authoritative.
|
||||
Any host-catalog result remains an advisory.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A profile with `opus` follows `opus[1m]` when it is the only advertised
|
||||
variation.
|
||||
- A catalog with `opus[270k]` and `opus[1m, fast]` remains ambiguous and uses
|
||||
the existing provider-default path.
|
||||
- An explicit advertised fallback remains stronger than inference.
|
||||
- Kandev never sends a model ID that the executor did not advertise.
|
||||
- Users receive a durable warning because the effective model differs from the
|
||||
saved request.
|
||||
- Provider-specific ranking logic does not enter the lifecycle policy.
|
||||
- Backend and frontend helpers need mirrored contract tests. The backend result
|
||||
remains authoritative when their input catalogs differ.
|
||||
- The historical `opus` to `opus[1m]` example does not authorize inference.
|
||||
- Provider-specific variation labels and catalog order do not establish a
|
||||
substitute model identity.
|
||||
- Any future variation policy requires a new accepted decision that is
|
||||
compatible with exact-profile identity.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# ADR-2026-09-15-explicit-profile-model-strictness: Make Exact Model Selection a Profile Opt-in
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-09-15
|
||||
**Area:** backend, frontend, persistence, workflow
|
||||
|
||||
## Context
|
||||
|
||||
PR #3473 makes existing profiles strict when automatic fallback is false and
|
||||
no explicit fallback is saved. These values previously permitted executor-default
|
||||
continuation in catalog mismatch cases. Existing stored values do not prove
|
||||
that a user selected strict behavior. Upgrading must not introduce that failure.
|
||||
|
||||
## Decision
|
||||
|
||||
Add a per-profile `require_exact_model` setting, default false for existing and
|
||||
new profiles. Strictness takes priority over dormant fallback choices. Turning
|
||||
it off restores those saved choices without rewriting them. Require a concrete
|
||||
model when strictness is enabled. Do not add a global or workspace override.
|
||||
|
||||
Compatible profiles retain the pre-PR selection/error behavior, including the
|
||||
single advertised variation rule. Strict profiles never infer variations and
|
||||
fail before inference when the requested model cannot be advertised and applied.
|
||||
Both paths retain executor authority, unchanged saved model IDs, and durable
|
||||
fallback warnings. No policy sends an unadvertised model.
|
||||
|
||||
This decision supersedes
|
||||
[implicit exact-profile identity](2026-09-06-exact-profile-model-identity.md).
|
||||
It replaces the blanket variation rejection recorded in
|
||||
[the variation decision](2026-09-07-unique-model-variation-resolution.md) with a
|
||||
compatible-only rule. The implementation is tracked in the
|
||||
[PR package](../plans/exact-profile-model-identity/plan.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
Upgrades preserve working mismatch launches without enabling broader automatic
|
||||
fallback. Profiles can enforce exactness independently across executors. The
|
||||
additional field must traverse storage, APIs, profile copies, runtime resolution,
|
||||
and all editors. Existing fallback values remain dormant while strictness is on.
|
||||
Office post-start provider routing remains separately workspace-owned.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Infer strictness from existing false/empty fields: changes existing launch
|
||||
behavior and cannot distinguish an explicit decision from a default.
|
||||
- Set automatic fallback true on every old profile: ignores explicit fallback
|
||||
models and tolerates errors that previously stopped the launch.
|
||||
- Replace current fields with an enum: adds migration scope and risks losing
|
||||
existing fallback/error distinctions for this compatibility fix.
|
||||
- Add global and profile settings: creates inheritance/precedence rules and
|
||||
broad effects unrelated to an individual profile's identity policy.
|
||||
@@ -0,0 +1,205 @@
|
||||
---
|
||||
created: 2026-09-14
|
||||
status: implemented
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
|
||||
system_design:
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
|
||||
legacy_specs: []
|
||||
---
|
||||
# Implementation Plan: Exact Profile Model Identity as an Explicit Opt-in
|
||||
|
||||
## Overview
|
||||
|
||||
Revise PR #3473 so existing remote-executor launches keep their pre-PR model
|
||||
fallback behavior. Add Require exact model as a per-profile opt-in, default off.
|
||||
Implement storage/API/runtime policy first, then profile editors, then end-to-end
|
||||
acceptance and public documentation. All new work orders are sequential.
|
||||
|
||||
This package was requested on 2026-09-15 and is implemented as a maintainer
|
||||
fixup on the contributor branch. The plan, work orders, requirements, design,
|
||||
tests, and public guidance are included with the implementation.
|
||||
|
||||
## Baseline and completed work
|
||||
|
||||
Implementation baseline: `561d2a8cf0d5c30224696304839a550952331ebe`.
|
||||
Reviewed PR head: `561d2a8cf0d5c30224696304839a550952331ebe`.
|
||||
The two intervening commits only retrigger CI; their tree diff is empty.
|
||||
Compatibility oracle: pre-PR merge base
|
||||
`ba960f973205854733e0dcd9afa355bdda3dddf6`.
|
||||
The implementation was based on this contributor head and preserves the
|
||||
completed transport and reuse fixes.
|
||||
|
||||
Task 01 records the completed strict-by-default implementation. Preserve its
|
||||
transport staging, replacement catalog event handling, single validated reuse
|
||||
lookup, and durable warnings. Its old inferred strict predicate is superseded
|
||||
by the new explicit field. Existing green tests do not prove upgrade compatibility.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- False-by-default persisted `require_exact_model` through every profile path.
|
||||
- Strict mode precedence over dormant fallback values; no destructive migration.
|
||||
- Compatible launch/error behavior, including runtime-only unique variations.
|
||||
- Shared launch/reset/rebind/recovery policy and explicit strict workflow reuse.
|
||||
- Desktop/mobile profile editors, settings discovery, copy, and public guides.
|
||||
- Actual store-upgrade-to-launch evidence and strict/non-strict regressions.
|
||||
|
||||
### Out of scope
|
||||
|
||||
Global/workspace/executor policy, runtime feature flags, provider authentication,
|
||||
Office post-start routing changes, a live-session model lock, new provider APIs,
|
||||
and unrelated PR cleanup. Do not recreate completed transport fixes.
|
||||
|
||||
## Technical approach
|
||||
|
||||
The [requirement](../../specs/agents/requirements/no-silent-model-fallback.md)
|
||||
and [policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
|
||||
own the behavior matrix, migration, precedence, and transport contracts.
|
||||
[Recovery and UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
|
||||
owns replacement-catalog handling, workflow eligibility, and profile surfaces.
|
||||
The [ADR](../../decisions/2026-09-15-explicit-profile-model-strictness.md)
|
||||
records why strictness is per profile and why old auto-fallback fields remain.
|
||||
|
||||
Extend the existing profile store and DTO contract, `StartModelPolicy`, profile
|
||||
resolvers, executor/backend adapters, and profile snapshots. Gate strict checks
|
||||
on the new field. Preserve legacy omissions on partial update. Compatible mode
|
||||
must not be implemented by setting `AutoFallback=true`: that changes fallback
|
||||
priority and error tolerance. Extend existing React shared fallback components.
|
||||
No new state-management or provider abstraction is needed.
|
||||
|
||||
## ASCII UI preview
|
||||
|
||||
### UI-01: Desktop profile, expanded Fallback settings
|
||||
|
||||
Entry: Settings > Agents > profile. Default state; strictness is off.
|
||||
|
||||
```text
|
||||
Start model [ saved model v ]
|
||||
Fallback settings v Executor default allowed
|
||||
+------------------------------------------------------------+
|
||||
| Require exact model [ OFF ] |
|
||||
| Stop before starting if the selected model cannot be used. |
|
||||
| Fallback settings do not apply while this is on. |
|
||||
+-----------------------------+------------------------------+
|
||||
| Automatic fallback [ OFF ] | Explicit fallback [ OFF ] |
|
||||
| Existing help and controls | Existing help and controls |
|
||||
+-----------------------------+------------------------------+
|
||||
[ Cancel ] [ Save ]
|
||||
```
|
||||
|
||||
Strict on: summary becomes "Exact model required". Both fallback cards remain
|
||||
visible and disabled, including their switches. Existing values remain saved.
|
||||
Strict off restores their prior states. The fallback selector appears only when
|
||||
its existing enable switch is on.
|
||||
A strict+empty-model validation error appears beside the model field; Save
|
||||
keeps the draft open. Collapsed state retains the summary and dirty indicator.
|
||||
|
||||
### UI-02: Phone profile, expanded Fallback settings
|
||||
|
||||
```text
|
||||
< Agent profile
|
||||
Start model
|
||||
[ saved model v ]
|
||||
Fallback settings v
|
||||
Executor default allowed
|
||||
+----------------------------------+
|
||||
| Require exact model [ OFF ] |
|
||||
| Stop before starting if the |
|
||||
| selected model cannot be used. |
|
||||
| Fallback settings do not apply |
|
||||
| while this is on. |
|
||||
+----------------------------------+
|
||||
| Automatic fallback [ OFF ] |
|
||||
| Visible helper text (i) |
|
||||
+----------------------------------+
|
||||
| Explicit fallback [ OFF ] |
|
||||
| Visible helper text (i) |
|
||||
+----------------------------------+
|
||||
[ Cancel ] [ Save ]
|
||||
```
|
||||
|
||||
The existing page/editor scrolls as one form. Help opens the shared inset
|
||||
bottom drawer and returns focus on close. Switch rows and help targets have
|
||||
at least 44px touch hit areas; desktop ordinary controls keep 28px sizing.
|
||||
Strict-on, collapsed, and validation states have the same semantics on phone.
|
||||
Long translations wrap without horizontal overflow or hiding Save.
|
||||
|
||||
Order, grouping, visible disabled values, and shared state are requirements;
|
||||
ASCII spacing and the illustrative model names are not pixel specifications.
|
||||
UI-01/UI-02 map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
|
||||
|
||||
## Tests
|
||||
|
||||
The following checks were run after implementation.
|
||||
|
||||
| Acceptance | Evidence |
|
||||
| --- | --- |
|
||||
| 001.1/.4/.5, 002.1 | Lifecycle policy table and focused lifecycle run passed. It covers strict/compatible selection, fallback precedence, apply errors, and unique variations. |
|
||||
| 001.3/.6 | SQLite migration, round-trip, explicit clear, schema replay, controller validation, and generated discovery checks passed. Postgres evidence was not run because no isolated `KANDEV_TEST_POSTGRES_DSN` was available. |
|
||||
| 001.1/.3/.8 | Lifecycle reset, rebind, replacement, and profile-resolution regressions passed in the focused run. |
|
||||
| 001.8 | Replacement-client catalog, cancellation, and strict reset/rebind tests passed in the focused lifecycle run. |
|
||||
| 001.9 | Focused orchestrator model/profile/reuse/drift tests passed, including strict unknown drift and the validated empty candidate path. |
|
||||
| 001.2/.10 | Existing desktop/mobile mismatch E2E tests passed with explicit strict fixtures and persisted compatible warnings. |
|
||||
| 001.6/.7 | Frontend normalization, settings, editor, dirty/reconciliation, and CLI tests passed; typecheck, i18n checks, and targeted lint passed. |
|
||||
|
||||
## E2E tests
|
||||
|
||||
Extend existing specs; do not replace strict fixtures with compatible fixtures
|
||||
and lose strict coverage. Set `require_exact_model=true` in strict fixtures.
|
||||
|
||||
| File under apps/web/e2e/tests | Project | Acceptance and scenario |
|
||||
| --- | --- | --- |
|
||||
| `settings/no-silent-model-fallback.spec.ts` | chromium | 001.6/.7/.10: default off, enable/save/reload, disable restores dormant settings, strict validation keeps form open, desktop help and dimensions |
|
||||
| `settings/mobile-no-silent-model-fallback.spec.ts` | mobile-chrome | 001.6/.7: same edit/save/reload flow, drawer dismiss then toggle/save, 44px hit targets, no overflow, long labels |
|
||||
| `session/model-mismatch-warning.spec.ts` | chromium | 001.1/.2/.3/.4/.5: old-style profile omits field and starts on default with one reloaded warning; explicit strict profile fails before prompt; explicit fallback and auto=true remain distinct |
|
||||
| `session/mobile-model-mismatch-warning.spec.ts` | mobile-chrome | 001.1/.2/.6: phone selection/launch reflects saved compatible/strict policy; warning survives reload |
|
||||
|
||||
Mock E2E proves the user flow. The store-to-transport regression proves actual
|
||||
migration compatibility; the Kubernetes transport test proves replacement
|
||||
catalog ownership. None substitutes for the others.
|
||||
|
||||
## Work orders
|
||||
|
||||
- [x] [Task 01: Historical strict identity implementation](task-01-enforce-launch-identity.md)
|
||||
- [x] [Task 02: Persist and apply explicit strictness](task-02-explicit-profile-policy.md)
|
||||
- [x] [Task 03: Expose profile controls on desktop and phone](task-03-profile-strictness-controls.md)
|
||||
- [x] [Task 04: Prove user flows and update public guides](task-04-compatibility-acceptance.md)
|
||||
|
||||
## Verification results
|
||||
|
||||
Implementation checks passed on 2026-09-15 unless noted below:
|
||||
|
||||
- `python3 scripts/list-docs.py validate`: 269 decisions and 902 specifications.
|
||||
- `python3 scripts/lint-spec-files.test.py`: 36 tests passed.
|
||||
- `python3 scripts/lint-spec-files.py --all`: all specification files passed.
|
||||
- `git diff --check`: passed.
|
||||
- Backend focused lifecycle, settings, controller, handlers, executor, backendapp,
|
||||
and orchestrator checks passed. A broader combined run reached unrelated
|
||||
pre-existing orchestrator failures and an SSH close test timeout; the changed
|
||||
focused tests passed.
|
||||
- Frontend typecheck and 83 focused Vitest tests passed.
|
||||
- Desktop settings E2E: 3 passed. Mobile settings E2E: 3 passed.
|
||||
- Desktop session E2E: 2 passed. Mobile session E2E: 2 passed.
|
||||
- Public docs validators and specification validators passed.
|
||||
- `go run ./cmd/settings-catalog -check`, `pnpm run i18n:check`, and
|
||||
`pnpm run i18n:ratchet` passed.
|
||||
- Package-relative links and work-order REQ/AC references resolve.
|
||||
- Catalog queries discover the amended specs and the new decision.
|
||||
|
||||
The Postgres migration check remains explicitly pending until an isolated test
|
||||
DSN is available. The implementation does not change the Postgres migration
|
||||
contract, but SQLite and all application projections are covered.
|
||||
|
||||
## Risks
|
||||
|
||||
- Missing a DTO/draft/copy path can silently clear or drop strictness.
|
||||
- A bulk auto-fallback migration can change fallback priorities and tolerated errors.
|
||||
- Treating a recovery timeout as transport success can hide a broken session.
|
||||
- Old session snapshots omit the new field; they must not imply strictness.
|
||||
- Restoring compatible variation selection must never affect strict mode or edit saved IDs.
|
||||
- Existing custom TUI/dynamic profiles do not have an enforceable concrete ACP model.
|
||||
- Supported Postgres migration evidence requires an isolated test database; a skipped test is not a pass.
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: "01-enforce-launch-identity"
|
||||
title: "Enforce exact profile model identity before inference"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
acceptance_criteria:
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
|
||||
system_design:
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
|
||||
---
|
||||
|
||||
# Task 01: Enforce Exact Profile Model Identity
|
||||
|
||||
## Historical scope
|
||||
|
||||
This work order is complete for the original PR implementation. The 2026-09-15
|
||||
amendment in [Task 02](task-02-explicit-profile-policy.md) supersedes its implicit
|
||||
strict predicate. Its transport, warning, and validated-reuse fixes remain.
|
||||
The original scope below is historical, not the current compatibility contract.
|
||||
|
||||
## Change
|
||||
|
||||
Apply the shared start-model policy before the first inference on every
|
||||
launch path: initial session start, context reset, and fresh ACP
|
||||
workspace-rebind sessions. A concrete profile with a non-empty model,
|
||||
`auto_fallback=false`, and no `fallback_model` must fail the launch before
|
||||
a prompt or tool call when the executor does not advertise the configured
|
||||
model; no speculative `SetModel` is sent for an unadvertised model.
|
||||
|
||||
Workflow step entry must also isolate stale runtime identity: a parked
|
||||
session whose persisted provider model disagrees with the destination
|
||||
profile's configured model policy is replaced with a fresh session before
|
||||
any auto-start prompt runs. Explicit `fallback_model` and `auto_fallback`
|
||||
profiles remain the only authorized deviation paths, each with one durable
|
||||
warning.
|
||||
|
||||
## Verification
|
||||
|
||||
- `go test ./internal/agent/runtime/lifecycle` covers
|
||||
`TestApplyStartModelPolicy` behavior for advertised, fallback, and
|
||||
unauthorized substitution cases (`start_model.go`,
|
||||
`start_model_executor_authority_test.go`).
|
||||
- `go test ./internal/orchestrator` covers session isolation on workflow
|
||||
entry (`event_handlers_workflow.go`,
|
||||
`event_handlers_workflow_profile_session_policy_resolution_test.go`,
|
||||
`event_handlers_workflow_profile_session_policy_test.go`).
|
||||
- Turn/message attribution and pre-prompt warnings agree on the effective
|
||||
model; failures never expose credentials or provider secrets.
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
id: "02-explicit-profile-policy"
|
||||
title: "Persist and apply explicit profile strictness"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
|
||||
acceptance_criteria:
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1
|
||||
system_design:
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
|
||||
---
|
||||
# Task 02: Persist and apply explicit profile strictness
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver an independently testable backend/API policy from persisted profile to prompt.
|
||||
|
||||
## In scope
|
||||
|
||||
Deliver an independently testable backend/API policy from persisted profile to prompt.
|
||||
|
||||
Add the additive false-default migration and profile field across storage,
|
||||
DTO/controller/handler mappings, discovery schema, copy/import paths, resolvers,
|
||||
internal projections, and session snapshots. Keep omitted partial updates intact.
|
||||
Validate strict+empty/dynamic/passthrough without invalidating legacy profiles.
|
||||
Regenerate discovery snapshots with the existing generator.
|
||||
|
||||
Extend the shared policy with explicit strictness and restore compatible
|
||||
selection/error behavior from the oracle. Update reset/rebind/replacement waits
|
||||
and workflow drift eligibility. Preserve fresh-client-only evidence, cancellation,
|
||||
validated reuse candidates, prompt ordering, and warning persistence.
|
||||
|
||||
Add a real legacy-store-to-agentctl/lifecycle launch regression. Exercise normal
|
||||
launch and all replacement boundaries. Do not only test synthetic policy structs.
|
||||
Parameterize the real store migration/round-trip evidence for SQLite and Postgres.
|
||||
Add projection tests proving true and false reach the runtime and snapshot.
|
||||
|
||||
## Out of scope
|
||||
|
||||
Global policy, provider authentication, Office post-start routing redesign,
|
||||
unrelated cleanup, and publication.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- A migrated old profile launches through the real lifecycle/transport boundary
|
||||
under the same missing-model conditions as before. Explicit strictness stops
|
||||
that launch before its prompt. Saved fallback fields remain identical.
|
||||
- The complete policy matrix, partial-update/copy paths, and generated contract
|
||||
pass. Strictness survives every projection, including dynamic candidate resolution.
|
||||
- Recovery and workflow tests preserve existing fixes while applying the new
|
||||
flag, with deterministic delayed events, cancellation, and empty reuse lookup.
|
||||
|
||||
|
||||
## Verification
|
||||
|
||||
Run from the repository root. Use TDD for changed logic; first record the
|
||||
behavioral failure, then run the listed checks after implementation.
|
||||
|
||||
```bash
|
||||
(cd apps/backend && go run ./cmd/settings-catalog)
|
||||
(cd apps/backend && go test ./internal/agent/settings/... ./internal/agent/runtime/agentctl ./internal/agent/runtime/lifecycle ./internal/orchestrator/... ./internal/backendapp)
|
||||
(cd apps/backend && go run ./cmd/settings-catalog -check)
|
||||
: "${KANDEV_TEST_POSTGRES_DSN:?Set an isolated Postgres test DSN before this check}"
|
||||
(cd apps/backend && go test -count=1 ./internal/agent/settings/store -run 'TestPostgres.*(RequireExactModel|Schema)')
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agent/settings/{models,dto,store,controller,handlers}/`
|
||||
- `apps/backend/internal/agent/settings/store/sqlite_require_exact_model_test.go` (new)
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/{types,profile_resolver,manager_profile,start_model}.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/{session,manager_interaction,manager_workspace_rebind,manager_kubernetes_refresh}.go`
|
||||
- `apps/backend/internal/agent/runtime/lifecycle/profile_model_upgrade_test.go` (new)
|
||||
- Existing lifecycle model, reset, rebind, and remote transport tests.
|
||||
- `apps/backend/internal/orchestrator/event_handlers_workflow.go` and profile session policy tests.
|
||||
- `apps/backend/internal/orchestrator/executor/{executor,executor_execute}.go` and tests.
|
||||
- `apps/backend/internal/backendapp/adapters.go` and projection tests.
|
||||
- `apps/web/lib/settings-discovery/{contract,profile-contract}.generated.json` (generator output).
|
||||
|
||||
## Dependencies
|
||||
|
||||
None; preserve Task 01 transport and candidate-lookup fixes.
|
||||
|
||||
## Risks
|
||||
|
||||
Do not convert old auto=false values into strict intent. Do not swallow
|
||||
initialization/transport errors as missing catalogs. Postgres tests must actually
|
||||
run with an isolated DSN. A stale cached profile must not lose true strictness.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
|
||||
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
|
||||
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
|
||||
- [Plan and regression matrix](plan.md)
|
||||
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
|
||||
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
|
||||
|
||||
## Results
|
||||
|
||||
Implemented on 2026-09-15. The profile field now has an additive SQLite
|
||||
migration, full DTO/controller/handler/store mappings, generated discovery
|
||||
contracts, runtime lifecycle and workflow propagation, strict and compatible
|
||||
selection behavior, and validation for unsupported profile kinds. Existing
|
||||
fallback values remain dormant while strictness is enabled and survive an
|
||||
explicit disable.
|
||||
|
||||
Focused settings, lifecycle, executor, backend adapter, and orchestrator tests
|
||||
passed. The broader combined backend command reached unrelated pre-existing
|
||||
orchestrator failures and an SSH close test timeout. The Postgres-specific
|
||||
check was skipped because `KANDEV_TEST_POSTGRES_DSN` was not available.
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
id: "03-profile-strictness-controls"
|
||||
title: "Expose strictness in both profile editors"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: ['02-explicit-profile-policy']
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
acceptance_criteria:
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
|
||||
system_design:
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
|
||||
---
|
||||
# Task 03: Expose strictness in both profile editors
|
||||
|
||||
## Summary
|
||||
|
||||
Expose the saved profile setting through both existing editor paths.
|
||||
|
||||
## In scope
|
||||
|
||||
Expose the saved profile setting through both existing editor paths.
|
||||
|
||||
Update normalized/HTTP types, serialization, draft state, dirty comparison,
|
||||
reconciliation, settings store options, discovery inventory, and editor submit
|
||||
payloads. Add the full-width strict row above the existing fallback cards.
|
||||
Preserve dormant values, disabled states, and deterministic summaries.
|
||||
Update the lighter CLI profile editor and shared fallback fields too.
|
||||
|
||||
Use visible localized copy and existing error presentation for strict+empty
|
||||
validation. Save errors retain the draft. Implement UI-01/UI-02 with shared state,
|
||||
existing page scrolling, touch drawer help, focus return, and target sizing.
|
||||
Translate en/pt-pt/zh-cn, generate zh-hk/zh-tw and pseudo; adjust summaries that
|
||||
currently imply all auto=false profiles are strict. Keep host warnings advisory.
|
||||
|
||||
## Out of scope
|
||||
|
||||
Global policy, provider authentication, Office post-start routing redesign,
|
||||
unrelated cleanup, and publication.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- True, false, and omitted fields round-trip through both editors; Save/Cancel,
|
||||
reload hydration, dirty state, and partial updates preserve the intended value.
|
||||
- Strictness overrides dormant settings in summaries and disabled controls;
|
||||
toggling it off restores them. Validation errors keep drafts open.
|
||||
- Both editor paths satisfy UI-01/UI-02, localization, and focused component
|
||||
tests. No global setting or second mobile policy is introduced.
|
||||
|
||||
## ASCII UI preview
|
||||
|
||||
### UI-01: Desktop profile, expanded Fallback settings
|
||||
|
||||
Entry: Settings > Agents > profile. Default state; strictness is off.
|
||||
|
||||
```text
|
||||
Start model [ saved model v ]
|
||||
Fallback settings v Executor default allowed
|
||||
+------------------------------------------------------------+
|
||||
| Require exact model [ OFF ] |
|
||||
| Stop before starting if the selected model cannot be used. |
|
||||
| Fallback settings do not apply while this is on. |
|
||||
+-----------------------------+------------------------------+
|
||||
| Automatic fallback [ OFF ] | Explicit fallback [ OFF ] |
|
||||
| Existing help and controls | Existing help and controls |
|
||||
+-----------------------------+------------------------------+
|
||||
[ Cancel ] [ Save ]
|
||||
```
|
||||
|
||||
Strict on: summary becomes "Exact model required". Both fallback cards remain
|
||||
visible and disabled, including their switches. Existing values remain saved.
|
||||
Strict off restores their prior states. The fallback selector appears only when
|
||||
its existing enable switch is on.
|
||||
A strict+empty-model validation error appears beside the model field; Save
|
||||
keeps the draft open. Collapsed state retains the summary and dirty indicator.
|
||||
|
||||
### UI-02: Phone profile, expanded Fallback settings
|
||||
|
||||
```text
|
||||
< Agent profile
|
||||
Start model
|
||||
[ saved model v ]
|
||||
Fallback settings v
|
||||
Executor default allowed
|
||||
+----------------------------------+
|
||||
| Require exact model [ OFF ] |
|
||||
| Stop before starting if the |
|
||||
| selected model cannot be used. |
|
||||
| Fallback settings do not apply |
|
||||
| while this is on. |
|
||||
+----------------------------------+
|
||||
| Automatic fallback [ OFF ] |
|
||||
| Visible helper text (i) |
|
||||
+----------------------------------+
|
||||
| Explicit fallback [ OFF ] |
|
||||
| Visible helper text (i) |
|
||||
+----------------------------------+
|
||||
[ Cancel ] [ Save ]
|
||||
```
|
||||
|
||||
The existing page/editor scrolls as one form. Help opens the shared inset
|
||||
bottom drawer and returns focus on close. Switch rows and help targets have
|
||||
at least 44px touch hit areas; desktop ordinary controls keep 28px sizing.
|
||||
Strict-on, collapsed, and validation states have the same semantics on phone.
|
||||
Long translations wrap without horizontal overflow or hiding Save.
|
||||
|
||||
Order, grouping, visible disabled values, and shared state are requirements;
|
||||
ASCII spacing and the illustrative model names are not pixel specifications.
|
||||
UI-01/UI-02 map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
|
||||
|
||||
Full context: [plan previews](plan.md#ascii-ui-preview). Rendered desktop/mobile
|
||||
acceptance runs in Task 04 after this work order.
|
||||
|
||||
## Verification
|
||||
|
||||
Run from the repository root. Use TDD for changed logic; first record the
|
||||
behavioral failure, then run the listed checks after implementation.
|
||||
|
||||
```bash
|
||||
(cd apps && pnpm install --frozen-lockfile)
|
||||
(cd apps/web && pnpm run i18n:zh-hant && pnpm run i18n:pseudo)
|
||||
(cd apps/web && pnpm exec vitest run lib/api/domains/agent-profile-normalize.test.ts components/settings/profile-form-fields.test.tsx components/settings/agent-profile-dirty.test.ts components/settings/agent-profile-reconciliation.test.ts components/agent/cli-profile-editor.test.tsx lib/settings-discovery)
|
||||
(cd apps/web && pnpm run typecheck && pnpm run i18n:check && pnpm run i18n:ratchet)
|
||||
(cd apps/web && pnpm exec eslint components/settings/profile-model-fields.tsx components/settings/profile-form-fields.tsx components/settings/model-fallback-settings-shell.tsx components/settings/profile-capability-helpers.tsx components/settings/agent-profile-page.tsx components/settings/agent-profile-page-state.ts components/settings/agent-profile-dirty.ts components/settings/agent-profile-reconciliation.ts components/agent/cli-profile-editor.tsx components/agent/cli-profile-fallback-fields.tsx lib/types/agent-profile.ts lib/api/domains/agent-profile-normalize.ts lib/state/slices/settings/types.ts lib/settings-discovery)
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/lib/types/agent-profile.ts`
|
||||
- `apps/web/lib/api/domains/agent-profile-normalize.ts` and tests.
|
||||
- `apps/web/lib/state/slices/settings/types.ts`
|
||||
- `apps/web/lib/settings-discovery/{profile-contract,coverage-inventory}.ts` and tests.
|
||||
- `apps/web/components/settings/profile-{form-fields,model-fields,capability-helpers}.tsx`
|
||||
- `apps/web/components/settings/model-fallback-settings-shell.tsx`
|
||||
- `apps/web/components/settings/agent-profile-{page,page-state,dirty,reconciliation}.ts*`
|
||||
- `apps/web/components/agent/cli-profile-{editor,fallback-fields}.tsx`
|
||||
- Existing component tests and new `apps/web/components/settings/agent-profile-dirty.test.ts`.
|
||||
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw,pseudo}/settings.json`
|
||||
|
||||
## Dependencies
|
||||
|
||||
['02-explicit-profile-policy']; preserve Task 01 transport and candidate-lookup fixes.
|
||||
|
||||
## Risks
|
||||
|
||||
The two editor paths have separate form data; a shared shell alone does not
|
||||
prove payload parity. A dormant auto=true value must not override strictness.
|
||||
Record generated locale changes and avoid unrelated translation drift.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
|
||||
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
|
||||
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
|
||||
- [Plan and regression matrix](plan.md)
|
||||
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
|
||||
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
|
||||
|
||||
## Results
|
||||
|
||||
Implemented on 2026-09-15. Desktop and CLI profile editors now share the
|
||||
localized strictness row, preserve dormant fallback values, disable fallback
|
||||
controls while strictness is enabled, and include the field in dirty state,
|
||||
normalization, reconciliation, save payloads, and settings discovery. The
|
||||
mobile layout keeps the existing drawer and form scroll owner.
|
||||
|
||||
Typecheck, i18n checks, targeted lint, and 83 focused frontend tests passed.
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
id: "04-compatibility-acceptance"
|
||||
title: "Prove user flows and update public guidance"
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: ['03-profile-strictness-controls']
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
acceptance_criteria:
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9
|
||||
- AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10
|
||||
system_design:
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-01.md
|
||||
- ../../specs/agents/system-design/no-silent-model-fallback-02.md
|
||||
---
|
||||
# Task 04: Prove user flows and update public guidance
|
||||
|
||||
## Summary
|
||||
|
||||
Complete desktop/mobile acceptance and align public guidance with the implementation.
|
||||
|
||||
## In scope
|
||||
|
||||
Complete desktop/mobile acceptance and align public guidance with the implementation.
|
||||
|
||||
Extend all four existing specs named in the plan's E2E matrix. Keep strict
|
||||
fixtures explicit and add omitted-field compatible fixtures. Edit/save/reload
|
||||
through the UI; inspect visible errors and one persisted warning. Retain backend
|
||||
pre-prompt assertions from Task 02; chat visibility alone does not prove no inference.
|
||||
Cover both editor surfaces, dormant fallback restoration, strict+empty validation,
|
||||
keyboard interactions, drawer dismissal/focus, touch bounds, and overflow.
|
||||
|
||||
Update the reference sections in `docs/public/agents-and-profiles.md` and the
|
||||
explanation in `docs/public/executors.md`. Explain per-profile default off, upgrade
|
||||
compatibility, exact full-ID selection, and ordinary apply errors vs automatic
|
||||
fallback. Search README/screenshots and linked specs/decisions for old implicit
|
||||
strict claims. Keep completed transport fixes and managed-runtime documentation.
|
||||
|
||||
Reconcile historical Task 01's scope notice, all new work-order results, and
|
||||
specification status after actual implementation checks pass. Refresh PR head/base
|
||||
read-only before handoff. Do not push, comment, or commit under this work order.
|
||||
|
||||
## Out of scope
|
||||
|
||||
Global policy, provider authentication, Office post-start routing redesign,
|
||||
unrelated cleanup, and publication.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Desktop and phone users can save strictness and observe the correct launch
|
||||
result; compatible warnings survive reload exactly once. Touch and keyboard
|
||||
interactions meet the design and both editor paths have rendered coverage.
|
||||
- Public profile/executor guidance matches the new default, fallback precedence,
|
||||
and error matrix, including legacy upgrade behavior.
|
||||
- Every required task check has a recorded result; pending or skipped Postgres
|
||||
evidence remains explicit. Completed transport/reuse regressions still pass.
|
||||
|
||||
## ASCII UI preview
|
||||
|
||||
Apply [UI-01 and UI-02](plan.md#ascii-ui-preview). This work order verifies those
|
||||
views and updates guide text; it does not introduce another layout.
|
||||
|
||||
```text
|
||||
Desktop: Strict [off/on] above [Automatic] [Explicit] cards -> Save
|
||||
Phone: Strict [off/on] -> Automatic -> Explicit -> Save
|
||||
Strict on: both fallback cards disabled, saved values visible.
|
||||
Help: tap -> inset drawer -> dismiss -> focus returns -> save draft.
|
||||
```
|
||||
|
||||
These views map to AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6 and .7.
|
||||
|
||||
## Verification
|
||||
|
||||
Run from the repository root. Use TDD for changed logic; first record the
|
||||
behavioral failure, then run the listed checks after implementation.
|
||||
|
||||
```bash
|
||||
(cd apps/web && pnpm e2e:run tests/settings/no-silent-model-fallback.spec.ts tests/session/model-mismatch-warning.spec.ts -- --retries=0)
|
||||
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/settings/mobile-no-silent-model-fallback.spec.ts tests/session/mobile-model-mismatch-warning.spec.ts -- --retries=0)
|
||||
node --test scripts/validate-public-docs.test.mjs
|
||||
node scripts/validate-public-docs.mjs
|
||||
python3 scripts/list-docs.py validate
|
||||
python3 scripts/lint-spec-files.test.py
|
||||
python3 scripts/lint-spec-files.py --all
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/e2e/tests/settings/no-silent-model-fallback.spec.ts`
|
||||
- `apps/web/e2e/tests/settings/mobile-no-silent-model-fallback.spec.ts`
|
||||
- `apps/web/e2e/tests/session/model-mismatch-warning.spec.ts`
|
||||
- `apps/web/e2e/tests/session/mobile-model-mismatch-warning.spec.ts`
|
||||
- `apps/web/e2e/tests/session/model-mismatch-warning-helpers.ts`
|
||||
- `docs/public/agents-and-profiles.md`, `docs/public/executors.md`
|
||||
- This plan, work orders, and paired requirement/design status and results.
|
||||
|
||||
## Dependencies
|
||||
|
||||
['03-profile-strictness-controls']; preserve Task 01 transport and candidate-lookup fixes.
|
||||
|
||||
## Risks
|
||||
|
||||
Use fresh managed production builds: do not pass --no-build after code changes.
|
||||
Run E2E commands sequentially with the guarded worker budget. Restore shared
|
||||
fixture mutations. Mock browser results cannot certify external provider auth.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- [Requirements](../../specs/agents/requirements/no-silent-model-fallback.md)
|
||||
- [Policy design](../../specs/agents/system-design/no-silent-model-fallback-01.md)
|
||||
- [Recovery/UI design](../../specs/agents/system-design/no-silent-model-fallback-02.md)
|
||||
- [Plan and regression matrix](plan.md)
|
||||
- Scoped AGENTS.md, existing tests beside the affected code, and compatibility
|
||||
behavior at `ba960f973205854733e0dcd9afa355bdda3dddf6`.
|
||||
|
||||
## Results
|
||||
|
||||
Implemented on 2026-09-15. Public agent/profile and executor guidance now
|
||||
describes compatible-by-default behavior, explicit strict opt-in, fallback
|
||||
precedence, host-probe advisories, and upgrade compatibility. The existing
|
||||
desktop and mobile settings and session mismatch specs passed with fresh
|
||||
production builds:
|
||||
|
||||
- desktop settings: 3 passed;
|
||||
- mobile settings: 3 passed;
|
||||
- desktop session mismatch: 2 passed;
|
||||
- mobile session mismatch: 2 passed.
|
||||
|
||||
Public-doc and specification validators passed. The Postgres check remains
|
||||
pending until an isolated test database is available.
|
||||
@@ -161,6 +161,8 @@ Select an agent, create a profile, then open **Settings > Agents > _Agent_ > _Pr
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Name | Label shown in workflow, session, and automation selectors. |
|
||||
| Model | Requested through ACP when the agent supports model selection. Leaving it unset uses the agent's default where the form allows that. |
|
||||
| Require exact model | Per-profile opt-in. When enabled, Kandev stops before inference unless the executor advertises and accepts the saved model. It disables fallback controls without erasing their saved values. |
|
||||
| Fallback settings | Compatible profiles can use an advertised explicit fallback or automatic provider-default continuation. If the saved model is absent and exactly one bracketed variation is advertised, Kandev can use that variation with a warning. |
|
||||
| Mode | Requested with ACP `session/set_mode`. The choices come from the installed agent. |
|
||||
| Configuration options | Dynamic ACP values requested with `session/set_config_option`. |
|
||||
| CLI flags | Enabled entries are tokenized and appended to the ACP launch command. |
|
||||
@@ -187,31 +189,6 @@ change makes a saved option value unsupported, Kandev removes that value after
|
||||
a successful resolution; a failed resolution keeps the draft unchanged so you
|
||||
can retry it.
|
||||
|
||||
### Model IDs and executor catalogs
|
||||
|
||||
The host model probe is an editing hint. The selected executor owns the model
|
||||
catalog at launch. Kandev resolves a saved model in this order:
|
||||
|
||||
1. Use the exact requested model when the executor advertises it.
|
||||
2. Use the advertised explicit fallback when the requested model is absent.
|
||||
3. Use one unique bracketed variation when the requested model is absent and
|
||||
the executor advertises exactly one matching ID.
|
||||
4. Use the agent's current or default model when no earlier choice applies.
|
||||
|
||||
Profiles with automatic fallback enabled keep the legacy behavior when the
|
||||
saved model is absent: Kandev ignores the explicit fallback and does not infer
|
||||
a variation. It uses the agent's current or default model instead.
|
||||
|
||||
For example, a saved `opus` model can launch as `opus[1m]` when that is the
|
||||
only advertised `opus[...]` ID. If the executor advertises both
|
||||
`opus[270k]` and `opus[1m, fast]`, Kandev does not choose either variation.
|
||||
Variation text is opaque and model IDs remain case-sensitive.
|
||||
|
||||
Kandev shows a warning when the launch result differs from the saved model.
|
||||
The saved profile remains `opus`; Kandev does not rewrite it after applying a
|
||||
unique variation or using the agent default. Recheck the executor catalog when
|
||||
the warning repeats after credentials, copied configuration, or agent updates.
|
||||
|
||||
### Use a dynamic profile
|
||||
|
||||
> [!EXPERIMENTAL]
|
||||
@@ -267,22 +244,33 @@ stale browser action does not replace a newer route decision.
|
||||
|
||||
The model list shown while editing a profile comes from a host probe. It is an
|
||||
editing hint, not a launch gate. A profile remains selectable when its saved
|
||||
model is missing from that host list. Profile selectors do not show a model
|
||||
warning for this difference. Inspect the model list in profile settings for
|
||||
discovery details. Authentication, installation, and probe-failure indicators
|
||||
remain visible on profile selectors.
|
||||
model is missing from that host list. Profile selectors show an amber warning
|
||||
icon for this difference. On a desktop pointer, hover or focus the icon to
|
||||
read its tooltip. On a touch device, select the icon to open its warning
|
||||
drawer. Inspect the model list in profile settings for discovery details.
|
||||
Authentication, installation, and probe-failure indicators remain visible on
|
||||
profile selectors.
|
||||
|
||||
At task launch, the selected executor's ACP catalog is authoritative. For
|
||||
profiles without automatic fallback, Kandev follows the four-step order above.
|
||||
For profiles with automatic fallback enabled, an absent saved model causes no
|
||||
model request, and Kandev ignores the explicit fallback and any variation.
|
||||
Kandev stores one warning in task chat with the requested model and the
|
||||
effective model when known. The warning also identifies the agent and executor
|
||||
and asks you to check credentials, copied configuration, and the agent version.
|
||||
At task launch, the selected executor's ACP catalog is authoritative. Kandev
|
||||
sends the requested model only when the executor advertises it. Profiles are
|
||||
compatible by default, so an unavailable saved model can use an advertised
|
||||
explicit fallback, one unique bracketed variation, or the executor's current
|
||||
or default model. Kandev records one warning with the requested and effective
|
||||
models when it continues with a different model. Automatic fallback allows
|
||||
provider-default continuation and ignores the saved explicit fallback.
|
||||
|
||||
The saved profile model is not changed. Optional portable configuration can
|
||||
copy selected allowlisted files into a remote executor, but it cannot guarantee
|
||||
that the host and executor expose the same model catalog.
|
||||
Enable **Require exact model** when the profile must keep the saved model. The
|
||||
executor must advertise and accept that model before the first prompt. An empty
|
||||
or unsupported catalog, an unavailable model, or a failed apply stops the
|
||||
session before inference. Kandev never sends an unadvertised model and never
|
||||
rewrites the saved profile model.
|
||||
|
||||
The host model list is only an editing hint. A missing host-probe model keeps a
|
||||
profile selectable and shows an advisory warning; the executor catalog decides
|
||||
the launch result. Upgrades and omitted API fields keep existing profiles
|
||||
compatible, with strictness off until a user enables it. Optional portable
|
||||
configuration can copy selected allowlisted files to a remote executor, but it
|
||||
cannot guarantee equal host and executor model catalogs.
|
||||
|
||||
### Monitor capability and subscription status
|
||||
|
||||
|
||||
+16
-24
@@ -101,32 +101,24 @@ Review the selected bundles before saving the profile.
|
||||
### Model selection in remote executors
|
||||
|
||||
The host model probe helps edit a profile, but it is not the launch authority.
|
||||
At launch, the selected executor's advertised ACP catalog decides the model.
|
||||
For profiles without automatic fallback, Kandev applies this deterministic
|
||||
order:
|
||||
At launch, the selected executor's advertised ACP catalog decides whether
|
||||
Kandev sends the saved model. Profiles are compatible by default. When the
|
||||
saved model is absent, Kandev can use an advertised explicit fallback, one
|
||||
unique bracketed variation, or the executor's current or default model. An
|
||||
automatic-fallback profile continues with the provider default and ignores its
|
||||
saved explicit fallback. Kandev writes one warning to task chat when it uses a
|
||||
different model.
|
||||
|
||||
1. An exact advertised model ID.
|
||||
2. An advertised explicit fallback.
|
||||
3. One unique advertised bracketed variation of the saved model.
|
||||
4. The agent's current or default model.
|
||||
Enable **Require exact model** on a profile when a substitution is not allowed.
|
||||
The executor must advertise and accept the saved model before the first prompt.
|
||||
An unavailable model, empty or unsupported catalog, or failed apply stops the
|
||||
session before inference. The session error reports the requested model, the
|
||||
effective model when known, and a stable reason. Kandev does not send an
|
||||
unadvertised model or rewrite the saved profile model.
|
||||
|
||||
For profiles with automatic fallback enabled, an absent saved model keeps the
|
||||
legacy behavior: Kandev ignores the explicit fallback and does not infer a
|
||||
variation. It uses the agent's current or default model instead.
|
||||
|
||||
For example, a saved `opus` model uses `opus[1m]` when that is the only
|
||||
advertised variation. With both `opus[270k]` and `opus[1m, fast]`, Kandev
|
||||
does not infer a choice and uses the agent's current or default model instead.
|
||||
It treats model IDs as case-sensitive and variation text as opaque.
|
||||
|
||||
Kandev writes one warning to task chat when the effective model differs from
|
||||
the saved model. The warning can list the requested model, effective model,
|
||||
agent, executor, and executor profile. It also tells you to check executor
|
||||
credentials, copied agent configuration, and the agent version. Kandev does
|
||||
not rewrite the saved profile model, including after applying a unique
|
||||
variation.
|
||||
Portable configuration can improve parity, but it does not guarantee equal
|
||||
host and executor model catalogs.
|
||||
A missing host-probe model remains an advisory warning and does not disable
|
||||
profile selection. Portable configuration can improve parity, but it does not
|
||||
guarantee equal host and executor model catalogs.
|
||||
|
||||
### Script behavior is runtime-specific
|
||||
|
||||
|
||||
@@ -5,131 +5,107 @@ created: 2026-08-23
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# No Silent Model Fallback Requirements
|
||||
|
||||
## Overview
|
||||
|
||||
Kandev applies an agent profile model against the model catalog from the
|
||||
selected executor. A different effective model must be deterministic and
|
||||
visible to the user. The agent system owns this contract because it owns
|
||||
profiles, ACP session startup, and model-selection warnings.
|
||||
Profiles retain their model choices when executor capabilities differ from the
|
||||
host. Users can require exact selection for an individual profile. Upgrading
|
||||
Kandev must not turn existing fallback behavior into strict launch failures.
|
||||
|
||||
The agent system owns this contract because it owns persisted profile policy.
|
||||
Task and Office execution consume that policy. This specification amends
|
||||
PR #3473 and is implemented by the profile policy and recovery designs.
|
||||
|
||||
## Terminology
|
||||
|
||||
- **Requested model:** The model ID stored in the agent profile.
|
||||
- **Explicit fallback:** The optional fallback model ID stored in the profile.
|
||||
- **Bare model ID:** A model ID that contains no `[` or `]` character.
|
||||
- **Model variation:** An advertised model ID with the exact form
|
||||
`<bare-model-id>[<non-empty-variant>]`. The variant contains no bracket
|
||||
character. Its content is otherwise opaque.
|
||||
- **Unique variation:** The only distinct advertised variation for a requested
|
||||
bare model ID.
|
||||
- **Strict profile:** a profile with Require exact model explicitly enabled.
|
||||
- **Compatible profile:** a profile with Require exact model disabled or absent.
|
||||
- **Requested model:** the effective model for the launch, including an
|
||||
intentional session override where the existing session contract permits it.
|
||||
- **Fallback:** a different model selected or retained for the current launch.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001: Use executor-authoritative model selection
|
||||
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001: Explicit strictness and visible fallback
|
||||
|
||||
**Intent:** Keep task launch operational without hiding a difference between
|
||||
the saved model and the effective executor model.
|
||||
**Intent:** Prevent unwanted substitutions when explicitly requested, while
|
||||
preserving working executor launches for existing profiles.
|
||||
|
||||
**User story:** As a user, I want Kandev to use the selected executor's model
|
||||
catalog and report any fallback, so that I can understand which model runs.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1:** When Require exact model is
|
||||
enabled, the executor shall advertise and apply the requested model before
|
||||
the initial prompt. Otherwise the attempt shall fail before inference.
|
||||
A fallback setting or advertised variation shall not bypass this rule.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2:** When a compatible profile uses
|
||||
a different model, the session shall show one durable warning for that
|
||||
selection decision. It shall include the requested and effective model when known.
|
||||
Reload and event replay shall not duplicate the warning.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3:** Existing profiles and newly
|
||||
created profiles shall have Require exact model off unless explicitly set.
|
||||
An upgrade shall preserve the model, fallback model, automatic fallback,
|
||||
and compatible launch outcomes. An absent setting shall not imply strictness.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4:** For compatible profiles, an
|
||||
advertised requested model shall take priority. With automatic fallback off,
|
||||
an advertised explicit fallback shall take priority over variation matching.
|
||||
If no alternate selection is available, the session shall continue on the
|
||||
executor current/default model with a warning. An empty catalog or unsupported
|
||||
model-selection method shall also permit this continuation.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5:** Compatible profiles shall retain
|
||||
existing apply-error behavior. An ordinary error applying an advertised model
|
||||
shall fail unless automatic fallback is enabled. Automatic fallback shall
|
||||
continue with a warning and ignore the configured explicit fallback.
|
||||
Initialization failures, disconnections, and cancellation shall remain errors.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.6:** Require exact model shall be a
|
||||
per-profile setting in Fallback settings, available on desktop and mobile.
|
||||
It shall default off. Enabling it shall disable the fallback controls without
|
||||
erasing their values. Disabling it shall restore their previous behavior.
|
||||
Save, reload, duplication, and supported profile export/import shall preserve
|
||||
the setting. Omitted fields in partial updates shall preserve a saved choice.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.7:** A collapsed Fallback settings
|
||||
section shall summarize the effective policy and expose unsaved changes.
|
||||
Strictness shall be keyboard and touch operable with visible explanatory copy.
|
||||
Phone help shall use the existing drawer interaction, with reachable touch
|
||||
targets, focus return, and no horizontal document overflow.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.8:** Launch, reset, fresh workspace
|
||||
rebind, and replacement-executor recovery shall apply the same profile policy.
|
||||
Replacement selection shall use only replacement-session evidence. Cancellation
|
||||
shall stop the attempt. A strict attempt without a ready replacement catalog
|
||||
shall fail; an initialized compatible attempt may continue with a warning.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.9:** Across different workflow steps,
|
||||
an explicitly strict destination shall replace a session whose effective model
|
||||
is different or unknown. Compatible destinations shall not force replacement
|
||||
solely because the effective model differs. Same-step intentional overrides
|
||||
shall keep their existing behavior. A validated empty reuse lookup shall create
|
||||
a fresh session without an unvalidated second lookup.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.10:** A missing host-probe model shall
|
||||
remain an advisory and shall not disable profile selection. Runtime selection
|
||||
shall not send an unadvertised model or rewrite the saved profile model.
|
||||
Enabling strictness without a concrete model shall produce a validation error.
|
||||
|
||||
#### Acceptance criteria
|
||||
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002: Compatible advertised variation selection
|
||||
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.1:** When the executor advertises
|
||||
the requested model, the system shall apply that exact model.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.2:** When the requested model is
|
||||
absent and the executor advertises the configured explicit fallback, the
|
||||
system shall apply the explicit fallback.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.3:** When no permitted advertised
|
||||
model applies, the system shall make no speculative model-selection call and
|
||||
shall continue with the provider current or default model.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.4:** When the effective model differs
|
||||
from the requested model, the system shall persist one structured warning
|
||||
that identifies the requested and effective models when known.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-001.5:** The system shall not rewrite the
|
||||
saved profile model from an executor model-selection decision.
|
||||
**Intent:** Preserve the pre-PR compatible selection order without treating a
|
||||
variation as an exact identity. This amendment restores the scoped behavior
|
||||
removed by the strict-by-default PR.
|
||||
|
||||
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002: Resolve one advertised model variation
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1:** This rule applies when strictness
|
||||
and automatic fallback are off. The bare requested ID must be absent, and no
|
||||
advertised explicit fallback must be available. Under these conditions, exactly
|
||||
one distinct advertised bracketed variation shall be selectable with a warning. Zero or multiple matches, malformed
|
||||
variations, and already-bracketed requests shall not authorize a guessed ID;
|
||||
the session shall use the executor default with a warning. Saved IDs shall
|
||||
remain unchanged. Strict profiles shall never infer a variation.
|
||||
|
||||
**Intent:** Preserve a user's bare model choice when a CLI replaces that model
|
||||
ID with one unambiguous bracketed variation.
|
||||
## Exclusions
|
||||
|
||||
**User story:** As a user, I want `opus` to resolve to `opus[1m]` when that is
|
||||
the only advertised variation, so that a provider catalog change does not move
|
||||
my session to an unrelated default model.
|
||||
No global, workspace, executor, environment, or release-toggle setting. No
|
||||
provider switching caused by this new field. Office post-start routing remains
|
||||
workspace-owned. No retroactive interruption or model change of running turns.
|
||||
No guarantee that invalid credentials, missing executables, or network failures
|
||||
can launch successfully. No new global enforcement system for model costs.
|
||||
|
||||
#### Acceptance criteria
|
||||
## System design and delivery
|
||||
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.1:** When automatic fallback is
|
||||
disabled, the exact requested model is absent, and an advertised explicit
|
||||
fallback exists, the system shall apply the explicit fallback before it
|
||||
considers an inferred variation. Automatic-fallback profiles shall retain
|
||||
their legacy no-selection behavior for an absent requested model.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.2:** When no advertised explicit
|
||||
fallback exists and the catalog contains exactly one distinct variation of a
|
||||
requested bare model ID, the system shall apply that advertised variation.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.3:** When the catalog contains zero
|
||||
or more than one distinct variation, the system shall not infer a model.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.4:** When the requested ID contains a
|
||||
bracket, the system shall treat it as an exact ID and shall not infer another
|
||||
variation.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.5:** Matching shall be case-sensitive
|
||||
and shall not parse, rank, or assign meaning to variation text.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.6:** When Kandev applies a unique
|
||||
variation, it shall keep the saved model unchanged and shall persist a
|
||||
warning that identifies the inferred effective model.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.7:** The host profile probe shall
|
||||
present unique-variation resolution as an advisory in the profile editor.
|
||||
It shall not become the launch authority or add a model warning to a profile
|
||||
selector. It shall not disable the profile.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-002.8:** The same resolution order shall
|
||||
apply at initial launch, context reset, and workspace rebind.
|
||||
|
||||
### REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003: Show model warnings at the point of action
|
||||
|
||||
**Intent:** Let users select a saved profile without treating a host discovery
|
||||
difference as evidence of an executor failure.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.1:** A host model-catalog difference
|
||||
shall not add an icon, message, tooltip, or help action to a profile selector.
|
||||
This applies to its options and its selected label, including missing models,
|
||||
one or several model variations, and empty or pending catalogs.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.2:** On desktop and mobile, an
|
||||
otherwise eligible profile shall remain selectable by keyboard or pointer.
|
||||
On touch devices, tapping its row shall select it without opening model help.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.3:** Existing authentication,
|
||||
installation, and capability-probe failure indicators shall remain visible.
|
||||
Their presence shall not depend on whether the saved model is advertised.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.4:** The profile editor shall retain
|
||||
its missing-model treatment, unique-variation advisory, and fallback controls.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.5:** When the executor applies the
|
||||
requested model successfully, a host catalog difference shall not cause a
|
||||
model-selection warning in task chat. Actual fallback warnings shall retain
|
||||
the persistence and visibility defined by requirement 001.
|
||||
- **AC-AGENTS-NO-SILENT-MODEL-FALLBACK-003.6:** Selecting a profile shall not
|
||||
rewrite its saved model, reasoning configuration, or fallback settings.
|
||||
|
||||
## Compatibility
|
||||
|
||||
The September 2026 selector amendment removes host model advisories from
|
||||
profile selection. It preserves executor model selection and profile editing.
|
||||
Delivery is tracked in the [implementation package](../../../plans/profile-selector-model-warnings/plan.md).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Ranking multiple variations by context size, speed, price, or display order.
|
||||
- Parsing provider-specific variation syntax beyond the bracketed ID shape.
|
||||
- Inferring a base model from an already bracketed request.
|
||||
- Rewriting the profile model to the current executor's advertised variation.
|
||||
- Changing Office post-start provider routing or mid-turn model switching.
|
||||
- Changing host discovery refresh, cache invalidation, or ACP model normalization.
|
||||
|
||||
## System design
|
||||
|
||||
The technical source is split into [part 1](../system-design/no-silent-model-fallback-01.md)
|
||||
and [part 2](../system-design/no-silent-model-fallback-02.md).
|
||||
- [Policy and persistence](../system-design/no-silent-model-fallback-01.md)
|
||||
- [Recovery and profile surfaces](../system-design/no-silent-model-fallback-02.md)
|
||||
- [PR implementation package](../../../plans/exact-profile-model-identity/plan.md)
|
||||
|
||||
@@ -4,640 +4,146 @@ system: agents
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003
|
||||
created: 2026-08-23
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# No Silent Model Fallback System Design Part 1
|
||||
# No Silent Model Fallback: Policy and Persistence
|
||||
|
||||
## Purpose and boundaries
|
||||
## Scope and mapping
|
||||
|
||||
This design defines executor-authoritative model fallback, including safe
|
||||
resolution from a bare requested model to one advertised bracketed variation.
|
||||
This design amends the strict-by-default implementation in PR #3473. The agents
|
||||
system owns profile policy; lifecycle applies it using executor evidence.
|
||||
[Part 2](no-silent-model-fallback-02.md) covers recovery and rendered surfaces.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| Requirement | Design sections |
|
||||
| --- | --- |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002` | [Unique model-variation resolution](#unique-model-variation-resolution) |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003` | [Profile selection and warning placement](#8-profile-selection-and-warning-placement) |
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
**Status**: implemented (executor-authority amendment 2026-08-15)
|
||||
**Date**: 2026-08-04
|
||||
**Slug**: `no-silent-model-fallback`
|
||||
|
||||
## Problem
|
||||
|
||||
Agents such as OMP are configured with models from multiple providers (e.g.
|
||||
Claude + GPT). When a provider's login/auth expires (e.g. Claude), its models
|
||||
become unavailable. Today Kandev silently compensates in several places:
|
||||
|
||||
1. **Session start (agentctl runtime)** — `SessionManager.InitializeSession`
|
||||
applies the profile's start model via ACP `SetModel` as *best-effort*:
|
||||
on failure it logs a warning and continues the session on the provider
|
||||
default model. `SetModel` itself fails fast when the model is not in the
|
||||
agent's advertised model list (`validateAvailableModel`), so the failure
|
||||
is known but ignored.
|
||||
2. **Profile reconciler (boot)** — `healProfile` overwrites a profile's
|
||||
start model with the probe's `CurrentModelID` when the configured model
|
||||
is no longer advertised. The user's explicit model choice is silently
|
||||
replaced.
|
||||
3. **Office post-start fallback** — when a launched run fails mid-session
|
||||
with a fallback-allowed error (`auth_required`, `model_unavailable`,
|
||||
…), `HandlePostStartFailure` silently re-dispatches the run to the next
|
||||
provider in the workspace routing order.
|
||||
4. **Frontend model lists** — model pickers have no concept of an
|
||||
unavailable ("gone") model; `clearStaleActiveModel` silently drops an
|
||||
active model that disappeared from the ACP list, so the session continues
|
||||
on whatever the agent picks.
|
||||
|
||||
**Bottom line: the host and executor can advertise different model catalogs.
|
||||
Kandev must keep the task operational and explain the effective model.**
|
||||
|
||||
## Goals
|
||||
|
||||
- A configured model that the executor does not advertise is never applied.
|
||||
The agent continues with its current or default model.
|
||||
- Every default or explicit fallback creates a persisted warning in task chat.
|
||||
The warning survives reload and shows the effective model when known.
|
||||
- A Claude model that is valid for the user's account can start in a cold,
|
||||
isolated executor even when the initial Claude ACP model list omits it.
|
||||
- "Gone" models render **greyed out and unselectable** in every model
|
||||
picker, while remaining visible so the user can see what was configured.
|
||||
- Agent profiles **keep** their previously configured start model even when
|
||||
gone (shown red + unselectable in the editor) instead of having it
|
||||
auto-healed.
|
||||
- Profiles remain selectable when the host probe does not advertise the saved
|
||||
model. The host probe is an editing hint, not an executor launch gate.
|
||||
- A new optional per-profile **agent fallback model** allows an explicit,
|
||||
single-model automatic switch when the start model becomes unavailable at
|
||||
session start. Kandev applies it only when the executor advertises it.
|
||||
Office post-start routing is unchanged and remains governed
|
||||
by the workspace routing configuration (see ADR
|
||||
`2026-08-08-provider-neutral-agent-error-recovery.md`): the profile's
|
||||
model policy is the owner of the session-start decision, not of office
|
||||
post-start provider fallback.
|
||||
- A new explicit per-profile toggle **"Fallback automatically to next
|
||||
model"** restores the legacy automatic-fallback behavior (session start
|
||||
best-effort + office routing re-dispatch). A failed apply continues with the
|
||||
agent default and creates a persisted warning. Enabling the toggle disables the
|
||||
optional fallback-model controls without clearing their saved value (the two
|
||||
are mutually exclusive opt-ins).
|
||||
- Agent-profile editors group both fallback choices in a collapsed **Fallback
|
||||
settings** disclosure. Expanding it shows the two choices side by side on
|
||||
desktop and as one vertical flow on phone-sized screens. Each choice keeps a
|
||||
short visible explanation and adds contextual help that works by hover or
|
||||
keyboard focus with a fine pointer and by tap on a coarse pointer.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Changing the workspace provider-routing configuration model (tiers,
|
||||
provider order, execution profiles) itself.
|
||||
- Provider-level auth flows (login/refresh UI) — only the *consequence* of
|
||||
auth expiry (unavailable models) is addressed.
|
||||
- Requiring equal model catalogs on the Kandev host and executor.
|
||||
- Requiring portable configuration copying before a task can start.
|
||||
- Mid-turn model switching on the live ACP session (retry the current turn
|
||||
on a different model) — fallback applies to the next attempt/launch, not
|
||||
to an in-flight turn.
|
||||
|
||||
## Definitions
|
||||
|
||||
- **Available models**: the model IDs an agent currently advertises —
|
||||
`hostutility.AgentCapabilities.Models` (probe cache, surfaced via
|
||||
`GET /api/v1/agents/available` and `GET /api/v1/agent-models/:agentName`)
|
||||
or the ACP session's `models_updated` list.
|
||||
- **Gone model**: a model ID that is configured (profile start model, active
|
||||
session model, fallback model) but absent from the currently advertised
|
||||
list. Deterministic on the frontend: `configured ∉ advertised`.
|
||||
- **Default-on-mismatch mode**: profile has `auto_fallback = false` and no
|
||||
`fallback_model`. If the executor omits the start model, Kandev skips model
|
||||
selection and the agent uses its default. Kandev persists a warning.
|
||||
- **Fallback-model mode**: profile has `auto_fallback = false` and a
|
||||
non-empty `fallback_model`. The only permitted automatic switch is to
|
||||
that single model when the executor advertises it. Otherwise, the agent uses
|
||||
its default and Kandev persists a warning.
|
||||
- **Auto-fallback mode**: profile has `auto_fallback = true`. Legacy
|
||||
behavior (session-start best-effort; office routing re-dispatch to next
|
||||
candidate). Every session-start deviation creates a warning.
|
||||
`fallback_model` is ignored.
|
||||
- **Cold isolated executor**: a non-standalone executor that does not share the
|
||||
host probe's Claude settings or model cache. Docker, remote Docker, Sprites,
|
||||
and SSH executors can have this property.
|
||||
|
||||
## Behavior Matrix
|
||||
|
||||
Per agent profile, one of three modes (precedence: `auto_fallback` wins
|
||||
over `fallback_model`):
|
||||
|
||||
| Scenario | Default-on-mismatch | Fallback-model | Auto-fallback |
|
||||
|---|---|---|---|
|
||||
| Session start, start model not advertised | Do not call `SetModel`. Continue on the agent default and persist a warning. | If the fallback is advertised, apply it and persist a warning. Otherwise, use the agent default and persist a warning. | Do not call `SetModel`. Continue on the agent default and persist a warning. |
|
||||
| Session start, advertised start model fails to apply | Fail explicitly. | Fail explicitly. | Continue on the agent default and persist a warning. |
|
||||
| Session start, model selection unsupported | Continue on the agent default and persist a warning. | Same | Same |
|
||||
| Mid-session model/auth failure (office run, post-start) | Unchanged ADR behavior: office re-dispatches via the workspace routing chain (`routingerr.Decide(ContextOffice)`; availability codes → `DecisionFallback`). The profile's model policy does **not** gate office fallback — the workspace routing configuration is the office authorization owner. | Same as default-on-mismatch: `fallback_model` is a session-start policy, not an office routing input. | Legacy: re-dispatch to next candidate in the provider order (unchanged). |
|
||||
| Boot reconciliation | Never overwrite a gone start model (keep it; UI shows it red). Same for a gone `fallback_model`. | Same | Same (reconciler is mode-independent). |
|
||||
| New-task / new-agent profile picker | Profile selectable without a host model advisory. | Same. | Same. |
|
||||
| Model picker (profile editor, session toolbar) | Gone models greyed out, unselectable, visible. | Same. | Same. |
|
||||
|
||||
`SetModel` failures that mean "this agent does not support model selection"
|
||||
(JSON-RPC `-32601`, `sessionmodel.MethodNone` / `IsMethodNotFound`) do not stop
|
||||
the launch. The agent uses its default and Kandev persists a warning.
|
||||
|
||||
The executor ACP catalog is authoritative for launch.
|
||||
The host probe remains an editing hint and does not block profile selection.
|
||||
|
||||
## Unique model-variation resolution
|
||||
|
||||
### Matching contract
|
||||
|
||||
ACP model IDs remain opaque and case-sensitive. Kandev recognizes only this
|
||||
structural relationship:
|
||||
|
||||
```text
|
||||
<requested>[<variant>]
|
||||
```
|
||||
|
||||
The requested ID must contain no `[` or `]` character. The advertised ID must
|
||||
start with the complete requested ID followed by `[`, end with `]`, and contain
|
||||
a non-empty variant with no bracket character. Kandev does not trim, parse, or
|
||||
rank the variant.
|
||||
|
||||
Examples:
|
||||
|
||||
| Requested | Advertised candidates | Result |
|
||||
| --- | --- | --- |
|
||||
| `opus` | `opus[1m]` | Apply `opus[1m]`. |
|
||||
| `opus` | `opus[270k]`, `opus[1m, fast]` | Do not infer. |
|
||||
| `opus[1m]` | `opus[270k]` | Do not infer. |
|
||||
| `opus` | `myopus[1m]`, `opus-extra[1m]` | Do not infer. |
|
||||
| `opus` | `opus[]`, `opus[1m][fast]` | Do not infer. |
|
||||
|
||||
Duplicate catalog rows with the same model ID count as one distinct candidate.
|
||||
This rule keeps the outcome stable when an agent repeats a catalog entry.
|
||||
|
||||
### Resolution order
|
||||
|
||||
For profiles with `auto_fallback = false`, the lifecycle applies this order
|
||||
after ACP initialization:
|
||||
|
||||
1. Apply the exact requested model when advertised.
|
||||
2. Apply the configured explicit fallback when advertised.
|
||||
3. Apply the requested model's unique advertised variation when one exists.
|
||||
4. Otherwise, make no model-selection call and keep the provider current or
|
||||
default model.
|
||||
|
||||
An unadvertised explicit fallback does not block step 3. More than one distinct
|
||||
variation blocks inference even when one candidate appears first or is the
|
||||
provider current model.
|
||||
|
||||
When `auto_fallback = true`, the legacy path takes precedence when the
|
||||
requested model is absent: Kandev ignores the explicit fallback and does not
|
||||
infer a variation. It makes no model-selection call and continues on the
|
||||
provider current or default model with a warning. Apply errors for an
|
||||
advertised model remain best-effort in that mode.
|
||||
|
||||
`applyStartModelPolicy` remains the single runtime owner. A pure helper returns
|
||||
the unique candidate or no candidate. Initial launch, context reset, and
|
||||
workspace rebind continue to call the same policy.
|
||||
|
||||
### Decision and warning contract
|
||||
|
||||
The typed decision adds the outcome `unique_variation` and the stable reason
|
||||
`unique_variation_applied`. `EffectiveModel` contains the advertised variation.
|
||||
`FallbackModel` remains reserved for a configured explicit fallback and is not
|
||||
overloaded with an inferred value.
|
||||
|
||||
Kandev calls `SetModel` only with the candidate's exact advertised ID. A failed
|
||||
call follows the existing advertised-model rule: fail the operation unless
|
||||
legacy `auto_fallback` permits provider-default continuation. A
|
||||
method-not-supported response also follows the current provider-default path.
|
||||
|
||||
The persisted `model_selection_warning` event uses the new reason and existing
|
||||
requested and effective model fields. The profile remains unchanged. The
|
||||
decision ID continues to include the requested model, reason, and effective
|
||||
model, so the warning stays idempotent for one session decision.
|
||||
|
||||
### Host advisory and mobile behavior
|
||||
|
||||
The frontend uses a small pure helper with the same case-sensitive matching
|
||||
table. This calculation is advisory because the host catalog can differ from
|
||||
the selected executor catalog.
|
||||
|
||||
When the host advertises one variation, the task profile option remains
|
||||
selectable without a host model advisory. The profile editor keeps the saved
|
||||
bare ID visible and describes the unique
|
||||
host variation instead of reporting that the model is simply gone. Selecting
|
||||
the advertised variation remains an explicit way to update the profile.
|
||||
|
||||
When the host advertises zero or multiple variations, the profile editor's
|
||||
missing-model presentation remains. The runtime can still reach a different decision from
|
||||
the selected executor catalog.
|
||||
|
||||
The task-create selector has no host model tooltip or help drawer.
|
||||
The profile editor uses its existing responsive selector. The durable
|
||||
chat warning uses the existing status-message layout on desktop and mobile.
|
||||
This change adds no nested scroll area or hover-only information.
|
||||
|
||||
### Tests and operational evidence
|
||||
|
||||
Backend table tests cover exact precedence, explicit-fallback precedence,
|
||||
one variation, duplicate rows, multiple variations, bracketed requests,
|
||||
case differences, malformed IDs, method-not-supported, and apply errors.
|
||||
Existing launch, reset, rebind, warning persistence, and reload tests cover the
|
||||
new decision outcome.
|
||||
|
||||
Frontend unit tests mirror the matching table and cover the task picker,
|
||||
profile editor, and localized status warning. Existing desktop and mobile model
|
||||
mismatch E2E flows add the unique and ambiguous catalog cases.
|
||||
|
||||
Structured lifecycle logs record the requested model, effective model, outcome,
|
||||
and distinct candidate count. They do not record credentials or configuration
|
||||
file contents.
|
||||
|
||||
No database migration is required.
|
||||
|
||||
## Related decisions
|
||||
|
||||
- [Let the Executor Own Model Selection](../../../decisions/2026-08-15-executor-authoritative-model-selection.md)
|
||||
- [Resolve Only One Advertised Model Variation](../../../decisions/2026-09-07-unique-model-variation-resolution.md)
|
||||
|
||||
## Backend Changes
|
||||
|
||||
### 1. Agent profile schema (new columns)
|
||||
|
||||
`agent_profiles` gains:
|
||||
|
||||
- `fallback_model TEXT NOT NULL DEFAULT ''` — optional single fallback model
|
||||
ID (ACP model ID, same vocabulary as `model`).
|
||||
- `auto_fallback INTEGER NOT NULL DEFAULT 0` — explicit opt-in to legacy
|
||||
automatic fallback.
|
||||
|
||||
Migration follows the existing `r.migrate.Apply("agent_profiles.<col>",
|
||||
"ALTER TABLE ... ADD COLUMN ...")` pattern in
|
||||
`apps/backend/internal/agent/settings/store/sqlite.go`. Wire through:
|
||||
|
||||
- `models.AgentProfile` (`internal/agent/settings/models/models.go`)
|
||||
- store scan/insert paths (`settings/store/sqlite.go`)
|
||||
- `dto.AgentProfileDTO` + create/update request structs
|
||||
(`settings/dto/dto.go`, `settings/controller/profile_crud.go`)
|
||||
- frontend `AgentProfile` type, `normalizeAgentProfile` /
|
||||
`toAgentProfilePayload` (`apps/web/lib/types/agent-profile.ts`,
|
||||
`apps/web/lib/api/domains/agent-profile-normalize.ts`)
|
||||
|
||||
Validation: `fallback_model` may be set independently; when `auto_fallback`
|
||||
is enabled the UI hides/disables the field and the backend ignores
|
||||
`fallback_model` at runtime (precedence rule). No cross-field rejection —
|
||||
saving both is allowed; runtime precedence is `auto_fallback`.
|
||||
|
||||
### 2. Reconciler stops healing gone models
|
||||
|
||||
`healProfile` in `internal/agent/settings/controller/reconciler.go` currently
|
||||
replaces a gone `p.Model` with `caps.CurrentModelID`. Change: keep the
|
||||
user-configured model when it is gone (log an info line; do not overwrite).
|
||||
The `p.Model == ""` seed-default branch is unchanged. Apply the same
|
||||
keep-when-gone rule to `fallback_model` (no auto-heal; UI surfaces it).
|
||||
Mode healing is unchanged (modes are not part of this feature).
|
||||
|
||||
### 3. Session start: executor-authoritative model application
|
||||
|
||||
In `internal/agent/runtime/lifecycle/session.go`, the start-model policy uses
|
||||
the executor session state after `InitializeSession`.
|
||||
|
||||
The policy returns a typed model decision with these values:
|
||||
|
||||
- Requested model.
|
||||
- Advertised fallback model, when one is applied.
|
||||
- Effective model, when the agent reports it.
|
||||
- Outcome and warning reason.
|
||||
- Whether Kandev called `SetModel`.
|
||||
|
||||
The policy applies this order:
|
||||
|
||||
1. If the start model is advertised, call `SetModel(start_model)`.
|
||||
2. If the start model is absent and the explicit fallback is advertised, call `SetModel(fallback_model)`.
|
||||
3. Otherwise, do not call `SetModel` and continue with the agent default.
|
||||
|
||||
An empty advertised list follows step 3.
|
||||
It does not authorize a speculative `SetModel` request.
|
||||
|
||||
If an advertised start or fallback model fails to apply, fail the launch.
|
||||
Transport and protocol errors remain explicit.
|
||||
|
||||
If `auto_fallback` is enabled, an apply error remains best-effort.
|
||||
The launch continues with the agent default and persists a warning.
|
||||
|
||||
If `sessionmodel.IsMethodNotFound(err)` is true, continue with the agent default.
|
||||
Persist a warning because the profile requested a model that Kandev could not apply.
|
||||
|
||||
The start-model policy owns every model-selection attempt.
|
||||
Later profile or configuration layers must not repeat a handled attempt.
|
||||
|
||||
The same policy applies after a context reset.
|
||||
A reset cannot send a model that the new executor session does not advertise.
|
||||
|
||||
### 3a. Persisted model-selection warning
|
||||
|
||||
If Kandev does not apply the requested model, it emits a provider-neutral
|
||||
`session_model_selection_warning` event.
|
||||
|
||||
The orchestrator persists one `status` message for the session-start decision.
|
||||
The message uses `metadata.variant = "warning"` and
|
||||
`metadata.kind = "model_selection_warning"`.
|
||||
|
||||
The metadata contains the reason, requested model, effective model, fallback
|
||||
model, agent ID, executor type, and executor profile ID.
|
||||
|
||||
The message content is structured and localized by the frontend status renderer.
|
||||
If the agent reports no effective model, the UI shows
|
||||
`provider default, model not reported`.
|
||||
|
||||
The warning includes this remediation guidance:
|
||||
|
||||
- Inspect the executor credentials.
|
||||
- Inspect copied agent configuration.
|
||||
- Inspect the agent version in the executor.
|
||||
|
||||
Message persistence is best-effort and does not stop the agent launch.
|
||||
Persistence errors are logged without model data from configuration files.
|
||||
|
||||
The persistence path uses an idempotency key for the session-start decision.
|
||||
Reconnect, replay, and browser reload do not create duplicate warning messages.
|
||||
|
||||
The existing ephemeral `session.model_fallback` signal becomes a compatibility
|
||||
projection of the provider-neutral decision event.
|
||||
|
||||
### 3b. Claude ACP model exposure in cold executors
|
||||
|
||||
The host probe can advertise a Claude model from its warm settings or model
|
||||
cache. A cold isolated executor can start with only the bridge's baseline model
|
||||
list. This difference does not prove that the configured model is unavailable
|
||||
to the user's account.
|
||||
|
||||
Before the initial Claude ACP process starts in a non-standalone executor, the
|
||||
lifecycle exposes the effective start model through Claude's documented launch
|
||||
environment. The effective model is the request model override when present.
|
||||
Otherwise, it is the profile start model. The lifecycle exposes an explicit
|
||||
profile fallback as a selectable custom model when `auto_fallback` is false.
|
||||
During workspace recovery, a persisted session runtime model is treated as the
|
||||
selected model for launch-environment derivation and takes precedence over the
|
||||
profile start model.
|
||||
|
||||
Provider launch environment values use fill-missing precedence. Request,
|
||||
executor, and profile environment values remain authoritative. The lifecycle
|
||||
does not replace an existing `ANTHROPIC_MODEL` or
|
||||
`ANTHROPIC_CUSTOM_MODEL_OPTION` value.
|
||||
|
||||
This behavior is an optional agent capability. Other agents receive no Claude
|
||||
environment values. A standalone Claude process keeps the current host behavior
|
||||
because it shares the settings and cache used by the probe.
|
||||
|
||||
SSH keeps its credential allowlist unchanged, but projects these non-secret
|
||||
Claude model values into the remote agent controller so its child process sees
|
||||
the same launch environment. Recovery fails before environment construction if
|
||||
the execution profile cannot be resolved, rather than silently dropping its
|
||||
model and environment values.
|
||||
|
||||
Kandev does not relax model validation after the ACP session starts.
|
||||
If Claude still omits the model, the executor-authoritative policy uses the default and warns.
|
||||
|
||||
Kandev does not copy the bridge private cache.
|
||||
The separate portable-configuration feature can copy `settings.json` after explicit user selection.
|
||||
|
||||
### 4. Office post-start failure gating (unchanged, ADR-governed)
|
||||
|
||||
`HandlePostStartFailure` in
|
||||
`internal/office/scheduler/routing_lifecycle.go` is **not** modified by this
|
||||
feature. Office post-start fallback authorization stays with the workspace
|
||||
routing configuration and provider chain
|
||||
(`routingerr.Decide(ContextOffice)`), per ADR
|
||||
`2026-08-08-provider-neutral-agent-error-recovery.md`. Rationale: the
|
||||
feature's model policy is owned by the session-start decision
|
||||
(`execution.AgentProfileID`); the office post-start path sees the stable
|
||||
office identity (`run.AgentProfileID`), and the two can disagree. Reading
|
||||
`agent.FallbackModel` / `agent.AutoFallback` there would create a second,
|
||||
conflicting policy owner. Office runs still get the session-start guarantee.
|
||||
Kandev does not send an unadvertised model, and it persists a warning.
|
||||
Mid-session Office failures keep the workspace-configured routing behavior.
|
||||
|
||||
Terminal office failures (for example after max attempts) surface an
|
||||
actionable "provider/model unavailable — change the model" hint: map
|
||||
`model_unavailable` / `auth_required` / `missing_credentials` /
|
||||
`subscription_required` codes onto the failure message via
|
||||
`routingerr.ModelUnavailableMessage` when composing it.
|
||||
|
||||
### 5. Error message mapping
|
||||
|
||||
Add a small helper (backend) that renders an actionable message for
|
||||
model/auth failure codes, e.g. `"Model unavailable: the configured model
|
||||
<id> is no longer available. Change the model in the agent profile."` Used
|
||||
by the session-start failure and the office terminal-failure path so both
|
||||
chat and run detail show the request-to-change-model copy. The frontend may
|
||||
additionally map the same codes to a banner (see frontend).
|
||||
|
||||
## Frontend Changes
|
||||
|
||||
### 6. Model pickers: disabled ("gone") support
|
||||
|
||||
`apps/web/components/model-config-selector.tsx`:
|
||||
|
||||
- `ModelSelectorOption` gains `disabled?: boolean` and
|
||||
`disabledReason?: string`.
|
||||
- `ModelRow` renders disabled options greyed (`opacity-40`,
|
||||
`cursor-not-allowed`), with the reason in a tooltip, and `onSelect` is
|
||||
guarded (`!option.disabled`). Follow the existing disabled pattern from
|
||||
`apps/web/components/combobox.tsx` (separate visual treatment + tooltip).
|
||||
|
||||
Session toolbar picker (`apps/web/components/task/model-selector.tsx`):
|
||||
|
||||
- `clearStaleActiveModel` in `apps/web/lib/ws/handlers/session-models.ts`
|
||||
stops clearing the active model when it disappears from the ACP list.
|
||||
Instead the active model is **kept and marked gone**: the picker shows it
|
||||
greyed out with a reason ("model no longer available — select a new
|
||||
model"), so the user is explicitly asked to change it.
|
||||
- `buildModelOptions` / `resolveAvailableModels` mark configured-but-absent
|
||||
models (profile model, active model) as `disabled`.
|
||||
|
||||
### 7. Profile editor rows
|
||||
|
||||
`apps/web/components/settings/profile-form-fields.tsx` (`CapabilitiesRow` /
|
||||
`ModelPicker`):
|
||||
|
||||
- **Start model**: when `profile.model` is not in the current model list,
|
||||
keep it as the current value but render it red
|
||||
(`text-destructive`) + disabled with a reason ("no longer available").
|
||||
- **Agent fallback row** (new, under Start model): optional select of the
|
||||
same model list bound to `profile.fallback_model`. It remains visible but is
|
||||
disabled when `auto_fallback` is ON, preserving the configured value while
|
||||
making the mutual exclusion understandable. It uses the same
|
||||
gone-red/disabled treatment if the fallback model itself is gone.
|
||||
- **"Fallback automatically to next model" toggle** (new row): a switch
|
||||
bound to `profile.auto_fallback`. When ON, the fallback-model controls are
|
||||
disabled. Helper text explains the semantics.
|
||||
- **Fallback settings disclosure**: both choices sit inside a semantic
|
||||
collapsible section that is closed on initial render. Its closed header
|
||||
summarizes the effective mode (executor default, automatic, or the configured explicit
|
||||
fallback) so saved state and hidden dirty state remain discoverable. The
|
||||
trigger is keyboard-operable, reports expanded state, and has a touch target
|
||||
of at least 44px.
|
||||
- **Responsive layout and help**: the expanded choices use two equal columns at
|
||||
the desktop breakpoint and one column below it. Each label has an info-icon
|
||||
button. Fine pointers expose localized help through a tooltip on hover and
|
||||
focus; coarse pointers open the same help in an inset bottom drawer. The
|
||||
visible helper sentence remains in the option card, so the icon is
|
||||
supplementary rather than the only explanation.
|
||||
- The lighter editor `apps/web/components/agent/cli-profile-editor.tsx`
|
||||
(`ModelModeFields`) gets the same disclosure, layout, help, and mutual
|
||||
exclusion behavior for parity.
|
||||
|
||||
All new copy is externalized via `t()` into the `settings` i18n namespace
|
||||
(`apps/web/src/locales/{en,pseudo,pt-pt,zh-cn}/settings.json`) — the i18n ratchet
|
||||
judges added lines even in unmigrated files.
|
||||
|
||||
### 8. Profile selection and warning placement
|
||||
|
||||
`apps/web/lib/state/slices/settings/types.ts` — `AgentProfileOption` gains
|
||||
`model`, `fallbackModel`, `autoFallback` (populated in
|
||||
`toAgentProfileOption`).
|
||||
|
||||
`apps/web/components/task-create-dialog-options.tsx`
|
||||
(`useAgentProfileOptions`) derives profile labels and eligibility without
|
||||
comparing the saved model with the host model catalog. Remove
|
||||
`advertisedModelIDs`, `ModelProbeWarning`, and `ModelProbeWarningIndicator` from
|
||||
this module, plus imports used only by those helpers. The hook no longer needs
|
||||
`useAvailableAgents` solely to produce model advisories.
|
||||
|
||||
Both `renderLabel` and `renderTriggerLabel` use the same profile presentation.
|
||||
Keep the option interface compatible with its consumers. Preserve profile
|
||||
eligibility, recent-use ordering, names, logos, and CLI passthrough indicators.
|
||||
Keep `getCapabilityWarning` and its authentication, installation, and probe
|
||||
failure states. Those states describe agent health rather than a model mismatch.
|
||||
|
||||
Consumers include task creation, new subtasks, new sessions, quick chat,
|
||||
automation configuration, and Office setup. All receive this behavior from the
|
||||
shared hook. Do not add consumer-specific warning suppression flags.
|
||||
|
||||
Retain profile model/configuration fields and the editor's
|
||||
`findUniqueModelVariation`. After checking references, remove these unused
|
||||
selector keys from every locale:
|
||||
`profileStartModelNotAdvertisedOnHost` and
|
||||
`profileStartModelUniqueVariationOnHost`.
|
||||
|
||||
`apps/web/app/office/setup/agent-profile-setup-controls.tsx`
|
||||
(`useSelectableProfileOptions`) retains its Office eligibility filtering around
|
||||
the shared profile options.
|
||||
|
||||
#### Desktop and mobile composition
|
||||
|
||||
Keep the touch-usable combobox and shared selection logic. A row tap completes
|
||||
the temporary profile choice without another help drawer or an empty hit area.
|
||||
Preserve keyboard selection, focus return, picker-owned scrolling, and safe-area
|
||||
constraints. Assert no document horizontal overflow.
|
||||
|
||||
Use `e2e/tests/settings/mobile-no-silent-model-fallback.spec.ts` as the shipped
|
||||
flow and `components/task/mobile/mobile-picker-sheet.tsx` as the curated
|
||||
temporary-choice precedent. No picker-shell replacement is needed.
|
||||
|
||||
#### Rationale and compatibility
|
||||
|
||||
A host observation cannot establish the executor outcome. A neutral icon or
|
||||
better ID comparison would still report valid catalog differences during
|
||||
selection. Keep the existing executor-authority ADR and runtime behavior.
|
||||
This change needs no resolver, cache, schema, or new ADR. Explain warning
|
||||
placement in `docs/public/agents-and-profiles.md` when implementation ships.
|
||||
|
||||
The persisted `model_selection_warning` chat message renders through
|
||||
`apps/web/components/task/chat/messages/status-message.tsx`.
|
||||
The renderer uses localized copy and structured metadata.
|
||||
|
||||
The message appears in the normal chat flow on desktop and mobile.
|
||||
It does not require a new drawer or a hover-only control.
|
||||
|
||||
### 9. i18n
|
||||
|
||||
New keys in `apps/web/src/locales/{en,pseudo}/settings.json` (camelCase,
|
||||
`settings:` namespace), cover the gone-model hint and fallback controls.
|
||||
|
||||
New keys in the chat namespace cover the persisted model-selection warning.
|
||||
No added or edited line contains hardcoded user copy.
|
||||
|
||||
## Tests
|
||||
|
||||
Backend (Go, `*_test.go` beside source):
|
||||
|
||||
- Store: `fallback_model` / `auto_fallback` round-trip + migration.
|
||||
- Reconciler: gone start model is kept, not overwritten; empty model still
|
||||
seeded; gone fallback_model kept.
|
||||
- Runtime session start: an unadvertised start model causes no `SetModel` call.
|
||||
The session continues with the reported current or default model.
|
||||
- Runtime session start: an advertised explicit fallback is applied.
|
||||
An unadvertised fallback causes no call and the agent default remains active.
|
||||
- Runtime session start: an empty catalog and method-not-supported both continue
|
||||
with the agent default and create a model-selection warning.
|
||||
- Runtime session start: an advertised model apply error fails explicitly.
|
||||
Auto-fallback keeps best-effort behavior and creates a warning.
|
||||
- Runtime session start: each decision produces at most one model-selection
|
||||
attempt with no profile-layer retry.
|
||||
- Runtime launch environment: a non-standalone Claude launch exposes the
|
||||
effective start model before ACP initialization. It exposes an explicit
|
||||
fallback only when auto fallback is off. Request, executor, and profile
|
||||
environment values take precedence. Standalone Claude launches and other
|
||||
agents receive no new environment values.
|
||||
- Office post-start: unchanged — availability failures requeue via the
|
||||
workspace routing chain regardless of the profile's fallback settings
|
||||
(regression test pins that the profile policy does not gate office).
|
||||
- Model-decision event and warning metadata tests.
|
||||
- Orchestrator persistence tests for message type, warning metadata,
|
||||
idempotency, reload hydration, and persistence errors.
|
||||
|
||||
Frontend (Vitest, `*.test.ts(x)`):
|
||||
|
||||
- `model-config-selector`: disabled option not selectable; greyed class.
|
||||
- `session-models` WS handler: stale active model is kept (not cleared).
|
||||
- `useAgentProfileOptions`: every otherwise eligible host-mismatch profile
|
||||
remains selectable with no model advisory in either label. Cover canonical
|
||||
IDs, legacy bracketed IDs, unique and multiple variations, and empty catalogs.
|
||||
- Capability health warnings, recent-use ordering, disabled-profile filtering,
|
||||
and saved profile values remain unchanged by selector rendering.
|
||||
- Profile editor: gone start model renders red + disabled; auto-fallback keeps
|
||||
the explicit fallback choice visible but disables its controls.
|
||||
- Profile editors: fallback settings start collapsed; expanding exposes both
|
||||
choices, auto-fallback disables rather than removes the explicit fallback,
|
||||
and desktop tooltip help is available through pointer and keyboard focus.
|
||||
- `agent-profile-normalize`: new fields round-trip.
|
||||
- Status message: structured model-selection metadata renders localized
|
||||
requested, effective, agent, executor, and remediation text.
|
||||
|
||||
E2E (Playwright, `apps/web/e2e`):
|
||||
|
||||
- Mock backend (`KANDEV_E2E_MOCK=true`): create a profile whose start model
|
||||
is not in the host catalog. Make sure that the task-create picker keeps the
|
||||
profile selectable without a host model warning in the option or selected
|
||||
label. Select the profile with keyboard on desktop and a row tap on mobile.
|
||||
- Launch a profile whose executor advertises its exact model while the host
|
||||
omits it. Verify the selected model, no model-selection warning, and unchanged
|
||||
profile values after reload.
|
||||
- Launch with an executor catalog that omits the profile model. Make sure that
|
||||
no model-selection call occurs, the task continues, and chat shows one warning.
|
||||
- Reload the task page. Make sure that the warning remains in chat.
|
||||
- Desktop profile settings: the disclosure starts closed, expands to two
|
||||
horizontally aligned option columns, summarizes the current fallback mode,
|
||||
and exposes each info explanation on hover/focus.
|
||||
- Mobile profile settings: tapping the same disclosure reveals one stacked
|
||||
flow; tapping either 44px info target opens the localized help drawer without
|
||||
horizontal document overflow.
|
||||
|
||||
## Persistence & Migration
|
||||
|
||||
- `agent_profiles.fallback_model TEXT NOT NULL DEFAULT ''`
|
||||
- `agent_profiles.auto_fallback INTEGER NOT NULL DEFAULT 0`
|
||||
|
||||
Existing rows use `auto_fallback = 0` and no fallback model.
|
||||
This state means default-on-mismatch behavior.
|
||||
|
||||
If the executor omits the saved model, the agent uses its default and Kandev
|
||||
persists a warning. The saved profile model does not change.
|
||||
| REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001 | Persistence, policy, warnings, boundaries |
|
||||
| REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002 | Compatible selection order |
|
||||
|
||||
## Persistence and API
|
||||
|
||||
Add `RequireExactModel bool` to `settings/models.AgentProfile`, represented as
|
||||
`require_exact_model` in JSON/storage and `requireExactModel` in normalized web
|
||||
profile data. Use an additive `agent_profiles.require_exact_model INTEGER NOT
|
||||
NULL DEFAULT 0` migration through the existing dialect-aware migration path in
|
||||
`settings/store/sqlite.go`. Cover SQLite and Postgres. Do not rewrite existing
|
||||
`model`, `fallback_model`, or `auto_fallback` columns or reinterpret their values.
|
||||
New profiles and seeds also default false. Reopening the store is idempotent.
|
||||
|
||||
Wire create/read/update, scans/inserts, clone/duplicate, reconciler preservation,
|
||||
profile export/import, and the canonical settings discovery contract. Use pointer
|
||||
presence on partial updates, including the enabled-only fast path. An omitted
|
||||
field preserves an existing value; explicit false clears strictness. Create and
|
||||
legacy import without the field use false. Old clients must not accidentally
|
||||
clear an existing true value when editing another field. The response includes
|
||||
an explicit boolean. Use the existing profile contract generator for snapshots.
|
||||
|
||||
Validation uses the merged profile on updates: strictness requires a non-empty
|
||||
model on a concrete ACP profile. A dynamic selector or terminal-passthrough
|
||||
profile cannot provide this guarantee and rejects an explicit strict request;
|
||||
existing such profiles remain valid with false. Dynamic selection passes the
|
||||
chosen concrete candidate's policy through existing execution resolution.
|
||||
Do not redesign dynamic eligibility or Office routing.
|
||||
|
||||
Saved fallback choices may coexist with strictness as dormant values. Runtime
|
||||
precedence is `require_exact_model` first, then existing `auto_fallback`, then
|
||||
explicit fallback/compatible selection. This preserves values across toggling
|
||||
and avoids destructive normalization. UI prevents simultaneous active modes;
|
||||
API precedence makes combinations deterministic without extra booleans.
|
||||
|
||||
## Profile transport
|
||||
|
||||
Propagate the field through `settings/dto`, handlers/controller mappings,
|
||||
`lifecycle.AgentProfileInfo`, `profile_resolver.go`, both policy constructors in
|
||||
`manager_profile.go`, and `StartModelPolicy`. Propagate it through the internal
|
||||
`orchestrator/executor.AgentProfileInfo` projection and `backendapp/adapters.go`.
|
||||
Include it in the existing profile snapshot produced by
|
||||
`executor.resolveAgentProfileSnapshot`; missing legacy snapshot fields mean
|
||||
false. A snapshot is evidence, not a new competing source of profile policy.
|
||||
Keep current profile-resolution timing: saving affects the next launch/reset/
|
||||
rebind or cross-step decision, not an already-running turn. Preserve existing
|
||||
model override precedence within a session.
|
||||
|
||||
Frontend mappings include `lib/types/agent-profile.ts`, API normalization and
|
||||
serialization, settings store option conversion, editor drafts, dirty checks,
|
||||
reconciliation, and settings discovery. Trace every existing `auto_fallback`
|
||||
producer/consumer to check whether it also carries the new profile field.
|
||||
Do not add strictness to provider wire protocols: the host owns this policy.
|
||||
|
||||
## Shared policy
|
||||
|
||||
`applyStartModelPolicy` remains the single owner of `SetModel` decisions.
|
||||
Never send an ID absent from the current executor catalog. Later config layers
|
||||
must not repeat a handled selection. Exactness compares full IDs, including
|
||||
provider prefixes and bracketed suffixes.
|
||||
|
||||
For strict profiles, ignore dormant fallback choices. Require a non-empty
|
||||
requested ID, advertise it, and apply it before ready/initial prompt. Empty
|
||||
catalog, absent requested ID, unsupported selection, or selection error fails
|
||||
with sanitized evidence. Runtime guards also reject strict+empty if storage
|
||||
validation was bypassed. An intentional session override supplies the effective
|
||||
requested ID under the existing override contract; this setting is not a lock
|
||||
against explicit user model changes.
|
||||
|
||||
### Compatible selection order
|
||||
|
||||
Use merge base `ba960f973205854733e0dcd9afa355bdda3dddf6` as the compatibility
|
||||
oracle for selection, not the PR's new strict tests:
|
||||
|
||||
1. Empty requested model means no explicit selection and no mismatch warning.
|
||||
2. Apply the requested model if advertised.
|
||||
3. With automatic fallback on and the requested model absent, continue on the
|
||||
executor current/default model. Ignore saved explicit fallback and variations.
|
||||
4. Otherwise apply an advertised explicit fallback when available.
|
||||
5. Otherwise resolve one distinct advertised bracketed variation of a bare ID.
|
||||
Restore the removed `uniqueAdvertisedModelVariation` runtime behavior only
|
||||
here. Deduplicate matching IDs; reject empty/nested brackets, ambiguous
|
||||
matches, and already-bracketed requests. Do not rank suffixes or catalog order.
|
||||
6. Otherwise keep the executor current/default model and warn.
|
||||
|
||||
An empty catalog follows step 6. Unsupported model selection retains the
|
||||
provider default and warns for compatible profiles. Other advertised apply
|
||||
errors still fail unless existing automatic fallback permits continuation.
|
||||
Do not catch initialization failure, transport disconnect, or cancellation as a
|
||||
catalog mismatch. The setting does not make all failures recoverable.
|
||||
|
||||
| Runtime case | Strict on | Strict off, auto off | Strict off, auto on |
|
||||
| --- | --- | --- | --- |
|
||||
| Requested advertised and applies | Requested | Requested | Requested |
|
||||
| Requested absent, fallback advertised | Error | Explicit fallback | Executor default |
|
||||
| No fallback, unique variation | Error | Variation | Executor default |
|
||||
| Missing/empty catalog or no match | Error | Executor default | Executor default |
|
||||
| Selection method unsupported | Error | Executor default | Executor default |
|
||||
| Ordinary advertised apply error | Error | Error | Executor default |
|
||||
| Initialization fails/cancelled | Error | Error | Error |
|
||||
|
||||
The stricter PR behavior remains valuable when selected explicitly. Its tests
|
||||
must set the new field instead of relying on `auto_fallback=false`.
|
||||
|
||||
## Warnings and existing boundaries
|
||||
|
||||
Reuse `ModelSelectionDecision`, the lifecycle warning event, and the persisted
|
||||
`status` message with `metadata.kind=model_selection_warning`. Restore the
|
||||
`unique_variation` decision outcome and existing effective-model warning path
|
||||
for compatible variation selection. Preserve one warning per selection decision,
|
||||
requested/effective model attribution, unknown-effective-model text, and reload
|
||||
idempotency. Failed strict attempts emit errors, not successful fallback notices.
|
||||
No credentials or provider configuration content belongs in metadata.
|
||||
|
||||
Keep gone saved models visible and unselectable in editors without rewriting
|
||||
profile values. Host probes remain advisory. Do not restore editor-side ID
|
||||
replacement to achieve runtime compatibility. Office post-start routing remains
|
||||
owned by workspace policy; never repurpose `auto_fallback` or strictness as a
|
||||
new workspace routing gate. Existing authorization and secret sanitization apply.
|
||||
|
||||
Preserve existing provider-specific launch preparation, including cold Claude
|
||||
model exposure and request/executor/profile environment precedence. Dormant
|
||||
fallback choices must not authorize strict selection. This package adds no
|
||||
provider-specific environment contract, cache copying, or unadvertised selection.
|
||||
|
||||
## Decision
|
||||
|
||||
[Explicit per-profile exact model policy](../../../decisions/2026-09-15-explicit-profile-model-strictness.md)
|
||||
supersedes the implicit strict default and records why a global setting and a
|
||||
bulk automatic-fallback migration are not used.
|
||||
|
||||
@@ -3,73 +3,108 @@ status: current
|
||||
system: agents
|
||||
requirements:
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002
|
||||
- REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003
|
||||
created: 2026-08-23
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# No Silent Model Fallback System Design Part 2
|
||||
# No Silent Model Fallback: Recovery and Profile Surfaces
|
||||
|
||||
## Purpose and boundaries
|
||||
## Mapping and scope
|
||||
|
||||
This design records risks for executor-authoritative model fallback and unique
|
||||
variation resolution.
|
||||
This design completes [the policy design](no-silent-model-fallback-01.md).
|
||||
REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001 acceptance criteria .6/.7 map to profile
|
||||
surfaces, .8/.9 to recovery/workflow, and .2/.10 to warnings/advisories.
|
||||
|
||||
## Requirement mapping
|
||||
## Recovery and session ownership
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-002` | [Risks & Open Questions](#risks--open-questions) |
|
||||
| `REQ-AGENTS-NO-SILENT-MODEL-FALLBACK-003` | [Risks & Open Questions](#risks--open-questions) |
|
||||
Initial launch, context reset (`manager_interaction.go`), workspace rebind
|
||||
(`manager_workspace_rebind.go`), and Kubernetes replacement
|
||||
(`manager_kubernetes_refresh.go`) use the same resolved `StartModelPolicy`.
|
||||
Preserve completed PR transport staging and delayed `session_models` handling.
|
||||
A strict replacement waits for its own usable catalog, including an async
|
||||
catalog after an empty session response. Timeout with no usable catalog fails
|
||||
before inference. Never select from the previous published client on timeout.
|
||||
|
||||
## Migrated source detail
|
||||
A compatible replacement may continue after a bounded catalog wait when its
|
||||
session initialized successfully but advertised no usable models. Pass only
|
||||
replacement evidence (including absent/empty state) to the shared policy and
|
||||
persist its warning. Distinguish catalog absence from initialization/stream
|
||||
failure and context cancellation. Cancellation always stops the attempt.
|
||||
An empty non-nil snapshot is not proof of catalog readiness. Keep replacement
|
||||
publication, rollback, and conversation identity ordering already fixed by the PR.
|
||||
|
||||
## Risks & Open Questions
|
||||
In `sessionHasUnauthorizedExactModelDrift`, apply exact-model eligibility only
|
||||
when the destination profile explicitly requires exactness. Dormant auto/fallback
|
||||
values cannot authorize a different model for strict destinations. Unknown or
|
||||
missing effective model also requires a fresh cross-step strict session.
|
||||
Compatible destinations keep normal workflow reuse policy; model drift alone
|
||||
is no longer a replacement reason. Profile changes and other existing session
|
||||
eligibility rules still apply. Same-step explicit overrides remain intact.
|
||||
|
||||
- **Behavior change for existing profiles**: an unadvertised start model no
|
||||
longer stops the launch. Kandev uses the executor agent default and persists
|
||||
an actionable warning.
|
||||
- **Office post-start fallback remains workspace-routing-governed**: a
|
||||
default-mode profile's Office run can still be re-dispatched to another
|
||||
provider mid-session by the ADR office policy (availability codes →
|
||||
`DecisionFallback`). This is intentional — office authorization is the
|
||||
workspace routing configuration, not the execution profile — and is
|
||||
documented in the behavior matrix above.
|
||||
- **Probe staleness**: the advertised list can be stale (probe cached).
|
||||
The profile editor uses it only as a hint. Profile selectors do not render
|
||||
host model advisories. The executor session catalog owns the launch decision.
|
||||
- **Cold Claude model lists**: a valid restricted model can be absent from a
|
||||
cold bridge's initial list. Pre-session exposure lets the bridge include and
|
||||
select the configured model. If the bridge still omits it, Kandev uses the
|
||||
agent default and persists a warning.
|
||||
- **Context reset model changes**: this amendment covers the model selected
|
||||
before the initial process starts. It does not restart a live ACP bridge to
|
||||
expose a newly selected hidden model during context reset.
|
||||
- **Office vs. kanban surfaces**: both share the same agent-profile rows.
|
||||
The shared selector behavior covers kanban task creation and Office setup.
|
||||
Office run-detail routing surfaces are unchanged.
|
||||
- **Collapsed controls remain legible**: the disclosure header summarizes the
|
||||
effective mode, and dirty-state decoration is applied to the disclosure
|
||||
container so a collapsed section cannot conceal that it has unsaved changes.
|
||||
- **Hover is supplementary**: every info icon is focusable, and coarse-pointer
|
||||
devices receive the same content in a drawer. The visible option helper copy
|
||||
remains the baseline explanation.
|
||||
- **Provider-specific labels remain opaque**: `1m`, `270k`, and `fast` have no
|
||||
Kandev-defined order. More than one variation therefore fails closed to the
|
||||
existing provider-default path.
|
||||
- **Host and executor decisions can differ**: a unique host variation is only
|
||||
an advisory. The selected executor can advertise zero, one, or multiple
|
||||
variations at launch.
|
||||
- **Bracketed requests do not drift sideways**: a request such as `opus[1m]`
|
||||
does not infer `opus[270k]`. The user must select another explicit model.
|
||||
- **Legacy automatic fallback remains unchanged**: when `auto_fallback` is
|
||||
enabled and the requested model is absent, Kandev does not apply an explicit
|
||||
fallback or infer a variation. It continues with the provider default.
|
||||
- **Removal must be narrow**: authentication, missing-CLI, and failed-probe
|
||||
indicators remain. Profile-editor advisories and persisted task warnings
|
||||
retain their existing behavior.
|
||||
- **Evidence has limits**: a model warning does not prove a cache defect.
|
||||
Discovery refresh or normalization changes require separate root-cause
|
||||
evidence; this amendment does not change those contracts.
|
||||
Retain the validated candidate passed to the switch path and the one-lookup
|
||||
empty-candidate fix. Profile-read errors do not silently downgrade strictness.
|
||||
Test all callers of the shared drift check, including human-to-work transitions.
|
||||
A new conversation must not inherit a rejected provider resume identity.
|
||||
|
||||
## Profile surfaces
|
||||
|
||||
Entry point: Settings > Agents > concrete agent profile > Fallback settings.
|
||||
Also update the shared controls used by `components/agent/cli-profile-editor.tsx`.
|
||||
The setting applies to that profile on any executor. There is no global,
|
||||
workspace, or executor override and no added item under System Feature Toggles.
|
||||
|
||||
Extend `ModelFallbackSection` and `ModelFallbackSettingsShell`:
|
||||
|
||||
- Place Require exact model first, as a full-width row in the expanded section.
|
||||
- Show a visible helper: "Stop before starting if the selected model cannot be
|
||||
used. Fallback settings do not apply while this is on."
|
||||
- Strict on disables automatic and explicit fallback controls without clearing
|
||||
them. Strict off restores the old automatic/explicit interaction. A dormant
|
||||
auto=true must not win in the summary or control disabled state.
|
||||
- Keep the disclosure initially collapsed, with effective summaries such as
|
||||
"Exact model required", "Automatic fallback", "Fallback: {model}", or
|
||||
"Executor default allowed". Summaries and helper copy must agree with the
|
||||
compatible selection/error matrix, including default continuation when an
|
||||
explicit fallback is also absent.
|
||||
- Include the new field in dirty state, Save/Cancel, optimistic reconciliation,
|
||||
normalization, and reload hydration. Updating only strictness must not be
|
||||
mistaken for an enabled-only edit. Empty-model validation keeps the draft open.
|
||||
- Keep the saved start model unchanged. An unavailable host model does not
|
||||
disable the strict switch if the profile already has a concrete saved ID.
|
||||
- Use `t()` and settings namespace keys for all copy. Translate English,
|
||||
Portuguese, Simplified Chinese, and generated Traditional Chinese catalogs;
|
||||
regenerate pseudo. Do not publish copy that describes every auto=false profile
|
||||
as strict or promises a configured fallback is always the final alternative.
|
||||
|
||||
## Mobile contract
|
||||
|
||||
Nearest shipped exemplar: `ModelFallbackSettingsShell` with `FallbackOptionHelp`.
|
||||
Reuse its shared form state, collapsed disclosure, and `useTouchDrawer` help.
|
||||
Desktop keeps the strict row above two fallback columns. Phone uses one ordered
|
||||
vertical flow: strictness, automatic fallback, explicit fallback, existing Save.
|
||||
No separate phone policy or copied business logic.
|
||||
|
||||
This is an occasional settings edit; it remains inline on the profile page.
|
||||
Use an inset bottom drawer only for supplementary help. The existing page or
|
||||
editor scroll container remains the sole form scroll owner. Shared drawer
|
||||
primitives handle dynamic viewport height and safe-area spacing. Close help
|
||||
returns focus to its trigger without closing the form or losing draft values.
|
||||
|
||||
Ordinary desktop controls keep 28px sizing; touch row/help hit targets are at
|
||||
least 44px (both dimensions for icon buttons), scoped to phone/coarse pointers.
|
||||
Measure actual bounds and hit testing. Check long translated labels, disabled
|
||||
states, keyboard toggle/save, document overflow, and coarse-pointer tablets.
|
||||
The plan's UI-01/UI-02 previews define order and grouping, not pixel geometry.
|
||||
|
||||
## Verification and remaining limits
|
||||
|
||||
Use real store migrations for upgrade evidence, policy unit tests for the full
|
||||
matrix, and lifecycle transport tests for delayed replacement catalogs and
|
||||
cancellation. Pair model-policy tests with an actual migrated profile launch;
|
||||
a fabricated zero-value policy alone does not prove upgrade compatibility.
|
||||
Desktop and mobile E2E cover saved toggles, launch continuation/error, drawer
|
||||
interaction, and persisted warnings. A mock E2E catalog mismatch does not prove
|
||||
provider credentials or every external executor integration.
|
||||
|
||||
Keep public docs updates in the implementation work orders. The existing public
|
||||
pages now describe the implemented compatible-by-default policy.
|
||||
|
||||
Reference in New Issue
Block a user