Files
kandev/docs/plans/profile-disable/plan.md
T
2026-08-24 11:09:03 +00:00

126 lines
10 KiB
Markdown

---
spec: docs/specs/agents/requirements/profile-disable.md
created: 2026-08-01
status: implemented
---
# Implementation Plan: Disable an Agent Profile
## Overview
Add an `enabled` flag to `agent_profiles` (kanban-flavour profiles only),
expose it through the profile DTO/PATCH API, carry it into the frontend
profile type and the store's `AgentProfileOption`, and filter it out of every
profile *selection* surface (new task, new subtask, new session, handoff,
quick chat). Two settings toggles: one in the profile page header (dirty/save
flow), one in the `/settings/agents` profile list (immediate save). Existing
sessions and labels are untouched because filtering happens only where
profiles are offered as choices — the store keeps disabled profiles.
Order: backend persistence/contracts → frontend types + selection filtering →
settings UI → E2E. Each layer is independently testable.
## Backend
### Schema & store (`apps/backend/internal/agent/settings/store/sqlite.go`)
- Add migration `r.migrate.Apply("agent_profiles.enabled", ALTER TABLE agent_profiles ADD COLUMN enabled INTEGER NOT NULL DEFAULT 1)` beside the other `agent_profiles.*` migrations in `migrate()`.
- Add `enabled INTEGER NOT NULL DEFAULT 1` to the `CREATE TABLE IF NOT EXISTS agent_profiles` DDL (both the original table and the `recreateAgentProfilesWithoutModelCheck` new-table DDL, and include the column in that migration's copy lists so a legacy DB recreation preserves it).
- `CreateAgentProfile` INSERT: add `enabled` column + bind (`dialect.BoolToInt(profile.Enabled)`).
- `UpdateAgentProfile` UPDATE: add `enabled = ?` to the SET list + bind.
- `agentProfileSelectColumns`: add `enabled`; `scanAgentProfile`: scan into `var enabled int` and set `profile.Enabled = enabled == 1`.
### Model (`apps/backend/internal/agent/settings/models/models.go`)
- Add `Enabled bool json:"enabled" db:"enabled"` to `AgentProfile` (near `CLIPassthrough`/`UserModified`).
### DTO (`apps/backend/internal/agent/settings/dto/dto.go`)
- Add `Enabled bool json:"enabled"` to `AgentProfileDTO`.
### Controller (`apps/backend/internal/agent/settings/controller/profile_crud.go`)
- `CreateProfile`: set `Enabled: true` on the new profile (Go zero value is false; the DB default only applies when the column is omitted).
- `UpdateProfileRequest`: add `Enabled *bool`.
- `UpdateProfile`: apply `if req.Enabled != nil { profile.Enabled = *req.Enabled }`.
- `toProfileDTO`: map `Enabled: profile.Enabled`.
### Handler (`apps/backend/internal/agent/settings/handlers/handlers.go`)
- `updateProfileRequest`: add `Enabled *bool json:"enabled,omitempty"`; pass `Enabled: body.Enabled` into the controller call.
## Frontend
### Types & client
- `apps/web/lib/types/agent-profile.ts`: add `enabled?: boolean` to `AgentProfile` (identity section) and to `AgentProfilePayload`.
- `apps/web/lib/api/domains/agent-profile-normalize.ts`: `normalizeAgentProfile` picks `enabled` with fallback `true`; `toAgentProfilePayload` sets `enabled`.
- `apps/web/app/actions/agents.ts`: `updateAgentProfileAction` payload gains `enabled?: boolean`.
- `apps/web/lib/state/slices/settings/types.ts`: `AgentProfileOption` gains `enabled?: boolean`; `toAgentProfileOption` maps `enabled: profile.enabled ?? true` (every call site — settings routes, use-settings-data, WS handlers, SSR, agent pages — picks it up automatically).
### Selection filtering (hide disabled profiles from choices only)
- Define one shared `isSelectableAgentProfile(profile)` predicate that returns
`profile.enabled !== false`, preserving the enabled-by-default behavior for
legacy payloads. Every selector path below must use this helper rather than
duplicating the enabled check.
- `apps/web/components/task-create-dialog-options.tsx`: `useAgentProfileOptions` filters selectable profiles — covers new task, new subtask, new session, and quick-chat option lists.
- `apps/web/components/task-create-dialog-computed.ts`: `useExecutorProfileCompat`'s `compatibleAgentProfiles` memo filters disabled profiles — feeds autopick (`decideAgentProfileAutopick` last-used / workspace-default / first candidates) and the `noCompatibleAgent` submit gate.
- `apps/web/components/task/handoff-profile-menu-items.tsx`: `useHandoffProfiles` filters disabled profiles.
- `apps/web/components/task/new-session-dialog.tsx`: `useNewSessionDialogState` keeps the raw current-session profile for existing-session labels and selector visibility, while the new-session initial fallback picks the first selectable profile.
- `apps/web/components/quick-chat/quick-chat-setup.tsx`: only apply the workspace-default `default_agent_profile_id` when that profile is enabled, else start unselected.
### Settings UI
- `apps/web/components/settings/agent-profile-page.tsx`:
- `ProfileEditorHeader` gains an `enabled` prop and renders a labeled `Switch` (`@kandev/ui/switch`) + helper text ("Disabled profiles stay available for existing sessions but won't be offered when creating new tasks or agents").
- `useProfileEditorState` `isDirty` includes `draft.enabled !== savedProfile.enabled`.
- `useProfileSave` PATCH payload includes `enabled: draft.enabled`.
- Wire the switch through `ProfileEditor` → header.
- `apps/web/app/settings/agents/page.tsx`:
- `ProfileListItem` renders an `enabled` `Switch` beside the profile name; clicking it calls `updateAgentProfileAction(profile.id, { enabled: next })`, then syncs the store (`setSettingsAgents` with the updated profile + `setAgentProfiles` rebuilt via `toAgentProfileOption`) — the same shape as `useSyncAgentsToStore` in the profile page. Keep the switch as a sibling outside the row's navigation link so toggling never navigates.
## Tests
- **What:** store persists/reads `enabled` (default true, update to false, scan round-trip). **File:** `apps/backend/internal/agent/settings/store/sqlite_profile_enabled_test.go` (or extend `sqlite_migration_test.go`). **How:** in-memory sqlite repo; create → expect `Enabled == true`; update → `false`; re-read → `false`.
- **What:** migration backfills existing rows to enabled. **File:** store migration test. **How:** create DB at pre-migration schema, insert a row without the column, run migrations, read `enabled == 1`.
- **What:** PATCH `/api/v1/agent-profiles/:id` with `{"enabled": false}` persists and returns `enabled: false`. **File:** `apps/backend/internal/agent/settings/controller/profile_crud_test.go` (+ handler test in `handlers/`). **How:** controller test with fake repo; assert DTO carries `Enabled` and repo receives it.
- **What:** `toAgentProfileOption` carries `enabled`. **File:** `apps/web/lib/state/slices/settings/types.test.ts` (or existing settings slice test). **How:** unit test.
- **What:** `normalizeAgentProfile` defaults missing `enabled` to `true` and maps `false`. **File:** `apps/web/lib/api/domains/agent-profile-normalize.test.ts`. **How:** unit test.
- **What:** `useAgentProfileOptions` omits disabled profiles. **File:** `apps/web/components/task-create-dialog-options.test.tsx`. **How:** render hook with mixed list, expect only enabled options.
- **What:** autopick never resolves to a disabled profile (last-used / workspace default / first fallback). **File:** `apps/web/components/task-create-dialog-effects.test.ts` (exercises `decideAgentProfileAutopick` via the compat-filtered list). **How:** feed a compat list that excludes the disabled profile; assert decision picks an enabled id or "no-compatible".
- **What:** compatibility filtering removes disabled profiles before autopick. **File:** `apps/web/components/task-create-dialog-computed.test.ts` (or the closest dialog-computed test). **How:** feed mixed raw profiles through the executor compatibility path and assert the returned list contains only enabled profiles.
- **What:** `useHandoffProfiles` omits disabled profiles. **File:** `apps/web/components/task/handoff-profile-menu-items.test.ts`. **How:** unit test with mixed store items.
- **What:** profile page header toggle drives dirty state and PATCH payload. **File:** `apps/web/components/settings/agent-profile-page.test.tsx`. **How:** render with a profile, flip the switch, assert `isDirty` and the save action payload include `enabled`.
- **What:** `/settings/agents` list toggle calls the update action and refreshes the row. **File:** `apps/web/app/settings/agents/page.test.tsx` (or component test for `ProfileListItem`). **How:** mock `updateAgentProfileAction`, click the switch, assert the action payload and store sync.
## E2E Tests
- **Scenario:** GIVEN an existing profile, WHEN the user disables it from the profile settings page and opens the new-task dialog, THEN it is absent from the agent profile selector. **File:** `apps/web/e2e/tests/settings/agent-profile-disable.spec.ts` (pattern from `agent-profile-acp.spec.ts`). **What to verify:** toggle persists (page reload keeps it off), the selector in the task-create dialog does not list the profile, and the profile still appears under "Manage existing profiles by agent" with the toggle off; toggling it back on restores it to the selector.
## Implementation Waves And Parallel Candidates
Wave 1:
- [x] [task-01-backend-enabled-column](task-01-backend-enabled-column.md)
Wave 2:
- [x] [task-02-frontend-types-and-selection-filtering](task-02-frontend-types-and-selection-filtering.md)
Wave 3:
- [x] [task-03-settings-toggle-ui](task-03-settings-toggle-ui.md)
Wave 4:
- [x] [task-04-e2e](task-04-e2e.md)
## Risks
- Go zero-value pitfall: a fresh profile must default to `enabled = true` — the controller must set it explicitly, otherwise every new profile would be created disabled.
- The store's three read paths share `agentProfileSelectColumns`; adding the column there plus `scanAgentProfile` keeps all reads consistent (the file already documents this as the rule).
- The `recreateAgentProfilesWithoutModelCheck` migration rebuilds the table for legacy DBs; forgetting the new column there would silently drop `enabled` for upgraded installs.
- Disabled + workflow-locked profile: the selector shows "No compatible agent profiles" and blocks submit until the user re-enables the profile or changes the workflow — intended per spec, but worth confirming in review.