7.8 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 11-utility-settings | Expose utility agent settings | done | 11 |
|
plan.md |
|
|
|
Task 11: Expose utility agent settings
Summary
Deliver the domain through the shared settings tools and authorized resource lookup. Include its complete eligible field set, current UI result, and independent contract checks.
In scope
- Adopt utility names, prompts, enabled state, and canonical agent-profile bindings.
- Preserve built-in restrictions and dependency validation. Do not promote legacy agent/model migration inputs into new controls.
- Add an explicit create_utility_agent_kandev adapter if missing, with a stable settings envelope.
- Use profile discovery for authorized compatible choices and retain failure states.
- Reconcile utility drafts without executing utility prompts as part of settings validation.
- Register metadata, context schemas, typed updates, redacted reads, and authorized lookup in the production composition.
- Add domain aliases to the independent search-query suite and update the generated snapshots.
- Include shared DTO conversion, semantic validation, and required atomic patch behavior for every write interface.
- Use current domain events, or add scoped value-free invalidation when none exists.
- Add coverage bindings and scoped editor tests. Update
docs/public/agents-and-profiles.mdwith delivered behavior.
Out of scope
- New persistence owners, arbitrary database access, privilege changes, and unrelated lifecycle operations.
- Automatic merging of dirty drafts, new navigation layouts, and real provider credentials in tests.
Acceptance
- Registered MCP calls match the existing UI contract for every eligible field, including explicit empties and domain-specific errors.
- Unauthorized, invalid, and conflicting changes preserve invariants without partial writes or sensitive output. New atomic patches cover competing writers.
- Clean editors update live and survive reload. Dirty drafts survive until recovery, on desktop and phone.
Verification
Run from the repository root after the one-time workspace dependency install in Task 00. These new test paths and names are planned implementation outputs, not existing evidence.
rtk proxy go -C apps/backend test ./internal/utility/controller ./internal/utility/service ./internal/utility/profilebinding ./internal/utility/catalog ./internal/mcp/server ./internal/mcp/handlers
rtk proxy go -C apps/backend run ./cmd/settings-catalog --check
rtk pnpm --dir apps/web exec vitest run lib/settings-discovery/utility-settings-contract.test.ts components/settings/utility-settings-reconciliation.test.tsx
rtk pnpm --dir apps/web run typecheck
rtk pnpm --dir apps/web run i18n:check
rtk pnpm --dir apps/web e2e:run --project chromium tests/settings/utility-settings-mcp.spec.ts
rtk pnpm --dir apps/web e2e:run --project mobile-chrome tests/settings/mobile-utility-settings-mcp.spec.ts
rtk node scripts/validate-public-docs.mjs
rtk git diff --check
Add TestUtilitySettingsParity and TestUtilitySettingsAuthority in
apps/backend/internal/mcp/server/settings_utility_settings_test.go.
Use real registered tools plus domain fixtures, not only direct handler invocation.
Add domain tests for any changed persistence path, including rollback and concurrent updates.
When a SQL query changes, include SQLite/PostgreSQL behavior evidence under the existing domain test conventions.
E2E scenario
Create a disposable utility, select its profile through MCP, observe the settings page, and reject an invalid binding. Use disposable resources and mock providers. Restore user-level settings in cleanup, including after failures. Run desktop and phone separately with the managed runner and record discovered test counts.
Files likely touched
apps/backend/internal/utility/dto/dto.goapps/backend/internal/utility/controller/controller.goapps/backend/internal/utility/service/service.goapps/backend/internal/utility/profilebinding/apps/backend/internal/utility/catalog/ (new)apps/web/components/settings/utility-agents-section-save.test.tsxapps/backend/internal/backendapp/services.goand MCP handler composition.apps/backend/internal/mcp/server/settings_utility_settings_test.go(new).apps/web/lib/settings-discovery/utility-settings-contract.test.ts(new).apps/web/components/settings/utility-settings-reconciliation.test.tsx(new): clean updates, dirty conflicts, own acknowledgements, and late replies.apps/web/lib/settings-discovery/coverage-inventory.tsand generated snapshots.- Relevant domain store subscriptions, current editor state, and locale catalogs.
- The two E2E files named in Verification.
Dependencies
Task 10 completes the preceding slice. Tasks 00 through 04 establish inventory, schemas, generic tools, and draft-recovery behavior. The sequential order avoids conflicts in shared composition and generated snapshots.
Risks
- Updating profile bindings must not bypass the utility dependency resolver or overwrite personal utility defaults.
- Saved settings and active runtime state can differ. Responses must not claim an unobserved runtime change.
- Missing identity can look like an internal service caller. MCP must reject that case under enforced authentication.
Mobile contract
Reuse the current domain settings route, shared save contributor, and existing phone composition. Keep recovery inline with the existing discard action, one content scroll owner, and safe-area-aware controls. Prove touch access and no horizontal page overflow. No new modal or breakpoint layout is required.
Parallelism
sequential
Inputs
- Both system designs, especially Required domains, Mutation semantics, Relationships, and Visible results.
- Task 00's field inventory and each source contract listed above.
- Existing domain tests, profile parity tests, and nearby shipped settings E2E.
- Scoped AGENTS.md, /tdd, /mobile-parity, /e2e, and /docs-maintainer before implementation.
Results
Completed on 2026-09-09.
- Registered utility agent settings and their supported configuration fields.
- Preserved utility-agent ownership and computed/action boundaries.
- Covered utility descriptors and adapter behavior in the focused backend suite.