7.9 KiB
spec, created, status
| spec | created | status |
|---|---|---|
| docs/specs/agents/requirements/hide-disabled-profiles-nav.md | 2026-08-11 | complete |
Implementation Plan: Hide Disabled Agent Profiles from Left Panel Navigation
Overview
Mirror the shipped integrations feature ("Hide disabled integrations from
left panel navigation", docs/specs/integrations/requirements/enable-disable-toggle.md)
for agent profiles: a single install-wide, localStorage-backed boolean,
toggled from the agents settings page, that filters the Settings left
panel's Agents tree. No backend, HTTP, or WS change.
Surface scoped by the spec: the Settings left panel's Agents group
(components/app-sidebar/sections/settings/agents-group.tsx) — the only
left-panel surface where /settings/agents-flavor profiles (the ones with
the enabled flag) appear. The office sidebar's Agents section is out of
scope (office rows have no enabled concept).
Frontend
1. Hide-setting hook (mirrors the integrations hook)
- Add
apps/web/hooks/domains/settings/use-hide-disabled-agent-profiles-in-nav.ts, exportinguseHideDisabledAgentProfilesInNav()→{ hideDisabled: boolean; setHideDisabled: (next: boolean) => void }. - Storage key
kandev:agents:hideDisabledInNav:v1, defaultfalse, custom sync eventkandev:agents:hide-disabled-in-nav-changed. - Same
useSyncExternalStore+storage-event + custom-event shape asapps/web/hooks/domains/integrations/use-hide-disabled-integrations-in-nav.ts:readHideDisabled()readslocalStorage.getItem(...) === "true", swallows read errors (defaultfalse), andsetHideDisabledwrites then dispatches the custom event, throwing on a failed write.
2. Settings-page toggle
- Add
apps/web/app/settings/agents/hide-disabled-agent-profiles-setting.tsx, exportingHideDisabledAgentProfilesSetting: a bordered row with<Label htmlFor="hide-disabled-agent-profiles-in-nav">+ description +<Switch id="hide-disabled-agent-profiles-in-nav">, checked from the hook and togglingsetHideDisableddirectly (immediate save — the agents page has no floating save bar; its profile toggles are immediate-save too). Rendered on the agents settings page; with zero profiles there is no profile list to hide from, so the row is absent until the first profile exists (recorded in the spec). - Render it on
apps/web/app/settings/agents/page.tsxdirectly below the page header separator and above the "Installed Agents" list, so the setting appears before the first agent profile on the page (the restructured page lists profiles inside the installed-agent cards; page already at its lint line budget; the component is a separate file imported by the page). separate file imported by the page). - Locale keys (all four catalogs,
src/locales/{en,pseudo,pt-pt,zh-cn}/settings.json):hideDisabledAgentProfilesFromNav— "Hide disabled agent profiles from left panel navigation"hideDisabledAgentProfilesFromNavDescription— "When on, a disabled agent profile is removed from the left panel navigation even if it's still configured."- No em dashes (U+2014); mirror each locale's existing
hideDisabledIntegrationsFromNav*phrasing for pt-pt/zh-cn.
3. Settings-tree filter
- In
apps/web/components/app-sidebar/sections/settings/agents-group.tsx, readconst { hideDisabled } = useHideDisabledAgentProfilesInNav();and filter the flat-mapped profiles:agent.profiles.filter((p) => !hideDisabled || (p.enabled ?? true)). enabledabsent → treated as enabled (never hidden). TheDisabledBadgelogic is untouched.useAvailableAgents()already hydratessettingsAgents.items; no store change.
Tests
- Hook unit tests —
apps/web/hooks/domains/settings/use-hide-disabled-agent-profiles-in-nav.test.tsmirroringuse-hide-disabled-integrations-in-nav.test.ts(uses the samemakeLocalStorageMockhelper): defaults tofalse; reads"true"literally; treats"false"/"1"/"yes"/""as off;setHideDisabledpersists and updates state; custom-event propagation;getItemthrowing →false;setItemthrowing → throws. - Toggle component tests —
apps/web/app/settings/agents/hide-disabled-agent-profiles-setting.test.tsx(mock the hook): renders label/description and an off switch whenhideDisabledisfalse; switchcheckedmirrorshideDisabled;onCheckedChangecallssetHideDisabled. - Settings-tree filter tests — extend the "SettingsTree agents group"
describe in
apps/web/components/app-sidebar/sections/settings/settings-tree-render.test.tsx(add a hoistedhideAgentProfilesmock foruseHideDisabledAgentProfilesInNav, defaultfalse):- default off: disabled profile link still rendered (with "Disabled" badge) — existing test stays green;
- on: disabled profile link gone; enabled and legacy (no
enabledfield) profiles still rendered; - on, then profile re-enabled (
enabled: true): link rendered again.
- E2E —
apps/web/e2e/tests/settings/hide-disabled-agent-profiles-nav.spec.tsmirroringe2e/tests/integrations/hide-disabled-integrations-nav.spec.ts:- disable a seeded profile via
apiClient.updateAgentProfile(profile.id, { enabled: false }); /settings/agents→ Settings left panel (app-sidebar-settings-mode) Agents tree still lists the disabled profile (setting default off);- toggle
#hide-disabled-agent-profiles-in-navon → tree entry disappears (no reload), enabled/legacy entries remain; - re-enable the profile via
apiClient→ tree entry reappears with the setting still on; finallyrestore{ enabled: true }; the localStorage flag is per-test-context so it resets automatically.
- disable a seeded profile via
Verification commands
Per task, then once at the end (sequential; web only — no backend change):
cd apps && pnpm --filter @kandev/web test -- \
hooks/domains/settings/use-hide-disabled-agent-profiles-in-nav.test.ts \
app/settings/agents/hide-disabled-agent-profiles-setting.test.tsx \
components/app-sidebar/sections/settings/settings-tree-render.test.tsx
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web lint
cd apps/web && pnpm run i18n:ratchet && pnpm run i18n:check
E2E (task 03):
cd apps/web && pnpm e2e:raw --project=chromium e2e/tests/settings/hide-disabled-agent-profiles-nav.spec.ts
Implementation Waves
Execution remains sequential in the primary conversation.
Wave 1:
Wave 2:
Wave 3:
Task 01 owns the hook contract the other two consume; task 02 filters the tree; task 03 proves the user-facing flow end to end.
Risks
- Wrong surface. The office sidebar's Agents section must NOT be
filtered — office rows lack
enabled. The hook is consumed only byagents-group.tsx(settings tree) and the settings-page toggle; do not import it intoagents-section.tsx. - Legacy profiles.
enabled === falseis the only "disabled" value;undefinedmust stay visible, or users with legacy profiles lose nav entries they cannot explain. - i18n ratchets. The new component lives under
app/settings/agents/**(whole-file i18n guard): all copy must go throught(), and all four catalogs need the two new keys ori18n:parity/i18n:ratchetfail. - Settings-tree accordion.
/settings/agentsopens the agents group via the route-prefix accordion (settingsOpenGroupIdForPath), so the E2E can assert on expanded tree links without extra clicks; if the e2e navigates to a different settings route first, it must re-enter/settings/agentsto reopen the group.
Public documentation
None. The integrations equivalent ("hide disabled ... from left panel
navigation") is not documented in docs/public; this setting follows the
same precedent and needs no docs change.