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

257 lines
13 KiB
Markdown

---
spec: docs/specs/agents/requirements/profile-duplicate.md
created: 2026-08-11
status: complete
---
# Implementation Plan: Agent Profile Duplicate
## Overview
Add a one-click "duplicate" for agent profiles on the settings agents surface
(`/settings/agents` profile list and the per-profile settings page). A new
interlock-protected endpoint `POST /api/v1/agent-profiles/:id/duplicate`
copies the source profile's full configuration (model, mode, config options,
CLI flags, env vars, launcher prefix, auto-approve flags, enabled state, MCP
config row) into a fresh row named `<source> Copy`, broadcasts the existing
`agent.profile.created` WS event, and returns the new profile DTO.
## Backend
### Controller: `DuplicateProfile`
Add to `apps/backend/internal/agent/settings/controller/profile_crud.go`:
- `type DuplicateProfileRequest struct { ID string }`.
- `func (c *Controller) DuplicateProfile(ctx, req) (*dto.AgentProfileDTO, error)`:
1. `repo.GetAgentProfile(ctx, req.ID)`; map the "agent profile not found"
error to `ErrAgentProfileNotFound` exactly like `DeleteProfile` does
(the sqlite store wraps `sql.ErrNoRows` in a message containing
"agent profile not found").
2. Build a fresh `models.AgentProfile` copying every configuration field:
`AgentID`, `AgentDisplayName`, `Model`, `FallbackModel` (trimmed),
`AutoFallback`, `Mode`, `ConfigOptions` (through
`profileconfig.SanitizeConfigOptions` on a copied map),
`AllowIndexing`, `AutoApprove`, `CLIPassthrough`, `CLIFlags` (deep
copy of the slice), `EnvVars` (deep copy of the slice, keeping
`SecretID` refs), `CommandPrefix`, `UserModified: true`, and the office
enrichment configuration fields (`WorkspaceID`, `Role`, `Icon`,
`ReportsTo`, `SkillIDs`, `DesiredSkills`, `MaxConcurrentSessions`,
`CooldownSec`, `SkipIdleRuns`, `FailureThreshold` (copied pointer),
`ExecutorPreference`, `BudgetMonthlyCents`, `Settings`, `Permissions`).
Do NOT copy runtime state: `Status`, `PauseReason`, `LastRunFinishedAt`,
`ConsecutiveFailures`, `DeletedAt`, `MigratedFrom`, `CustomPrompt`,
`DangerouslySkipPermissions`.
3. Name: `strings.TrimSpace(source.Name) + " Copy"`. The name is persisted
data, not UI copy (same convention as seeded executor/repository names),
so the suffix is a plain string in Go.
4. Read the source's MCP config row when it has one (`repo
.GetAgentProfileMcpConfig(ctx, source.ID)`; tolerate `sql.ErrNoRows` /
nil); deep-copy `Servers` and `Meta` into a fresh
`models.AgentProfileMcpConfig` (ProfileID filled by the repo). A source
without a row leaves the copy without one — the default-config
semantics and boot `EnsureDefaultMcpConfig` cover MCP-supporting
agents.
5. `repo.DuplicateAgentProfile(ctx, store.DuplicateAgentProfileInput{...})`
— NEW atomic repository operation (adversarial review round 1): one
transaction inserts the row with the caller-provided `Enabled` state
(NOT forced true like `CreateAgentProfile`, so a disabled source never
becomes briefly selectable) and upserts the MCP config row. A failure
rolls back, leaving no partial copy. Rollback makes each attempt
atomic, but the endpoint is not HTTP-idempotent: a retried request
creates another row (the UI guards against double-clicks). The store
assigns the fresh UUID and a single `CreatedAt`/`UpdatedAt` pair,
which the returned DTO reflects (no stale timestamp after a second
write).
6. **Consistent snapshot (adversarial review round 5):** inside the
transaction the repository re-reads the source profile and MCP rows and
verifies their `updated_at` still match the revisions the copy was
built from (`ErrProfileChanged` / `ErrSourceProfileNotFound` otherwise);
WAL snapshot isolation aborts the write with a busy error if a
concurrent writer commits between the verification and the insert. The
controller retries (bounded, `maxDuplicateRetries = 2`) on
`ErrProfileChanged` / `ErrSourceProfileNotFound` / busy errors with a
fresh source read, so the copy always reflects one consistent snapshot.
7. Return `toProfileDTO(clone)`.
Env-var secret refs are copied verbatim; they were validated when the source
was created/updated, so no re-validation is needed.
### Handler + route
In `apps/backend/internal/agent/settings/handlers/handlers.go`:
- Register `api.POST("/agent-profiles/:id/duplicate", h.interlock,
h.httpDuplicateProfile)` next to the other `/agent-profiles/:id` routes.
- `httpDuplicateProfile`: require `:id`, call
`controller.DuplicateProfile`, map `ErrAgentProfileNotFound` → 404, other
errors → 500; on success broadcast
`ws.ActionAgentProfileCreated` with `{"profile": resp}` (same payload
shape as `httpCreateProfile`) and return the DTO with 200.
### Tests (backend)
- Controller, new file
`apps/backend/internal/agent/settings/controller/profile_duplicate_test.go`
(using the existing `newTestController` + `newFakeStore`):
- full-config copy: source with model/fallback/mode/config options/CLI
flags/env vars/command prefix/auto-approve/cli-passthrough duplicates
with equal fields, new ID, `Default Copy` name, `user_modified` true;
- disabled source → disabled copy stored in the single atomic write (no
follow-up enabled flip, timestamps match the stored row);
- MCP config row copied to the new profile ID with equal enabled/servers/meta
(extend the shared `fakeStore` in `reconciler_test.go` with an
`mcpConfigs` map + working `GetAgentProfileMcpConfig` /
`UpsertAgentProfileMcpConfig` + `DuplicateAgentProfile`, additively —
other tests only observe the existing nil behaviour);
- store failure propagates and leaves no partial copy;
- unknown ID → `ErrAgentProfileNotFound`;
- empty source name (`""` → `" Copy"` is acceptable; source names are
non-empty by validation, but pin the suffix behaviour).
- Store, new file `apps/backend/internal/agent/settings/store/sqlite_duplicate_test.go`:
sqlite `DuplicateAgentProfile` round-trip — fresh ID, full configuration
preserved, disabled copy stays disabled (not forced enabled), MCP row
copied, source untouched; no MCP row created when none passed.
- Handler, `apps/backend/internal/agent/settings/handlers/interim_settings_interlock_test.go`:
add `{method: POST, path: "/api/v1/agent-profiles/profile-1/duplicate"}`
to the route list that must return 403 without the interlock token.
- Handler test (mandatory, adversarial review round 9): an office-scoped
source (`WorkspaceID != ""`) returns 404 with zero broadcasts on any
channel — global or workspace-scoped — and the office profile is rejected
before MCP config is read or written. Also assert 404 mapping and the
`agent.profile.created` broadcast for kanban profiles, following
`agent_update_handlers_test.go`'s controller-stub pattern.
## Frontend
### API action
In `apps/web/app/actions/agents.ts` add:
```ts
export async function duplicateAgentProfileAction(profileId: string): Promise<AgentProfile> {
const raw = await agentSettingsRequest<unknown>(
`${apiBaseUrl}/api/v1/agent-profiles/${profileId}/duplicate`,
{ method: "POST" },
);
return normalizeAgentProfile(raw);
}
```
### List page: per-row Duplicate button
- `apps/web/app/settings/agents/profile-list-item.tsx`: accept an
`onDuplicate: (profile: AgentProfile) => void` prop; render an icon-only
button (copy icon, e.g. `IconCopy` from `@tabler/icons-react`) outside the
link, next to the enabled switch, with `aria-label` / tooltip via
`t("agents:duplicateProfileNamed", { name: profile.name })` and
`data-testid={`duplicate-profile-${profile.id}`}`.
- `apps/web/app/settings/agents/page.tsx`: thread `onDuplicate` through
`AgentProfilesSection`; add a `handleDuplicateProfile` wired like
`useProfileEnabledToggle` (POST via the action, then merge the returned
profile into `settingsAgents` + `agentProfiles` store slices atomically via
`useAppStoreApi().setState`, appending the new profile to its agent's
`profiles`; toast success/failure via `agents:duplicateProfileSuccess` /
`agents:failedToDuplicateProfile`). The `agent.profile.created` WS handler
already upserts the same profile; the direct merge keeps the UI consistent
even if WS is delayed. The merge (`applyProfileDuplicated` in
`use-profile-duplicate.ts`) dedupes by ID, preserves WS-delivered options
whose owning agent is absent, never lets a stale duplicate response clobber
a newer `agent.profile.updated` version (newer `updatedAt` wins), and
always rebuilds the copy option with the known agent metadata.
### Profile settings page: header Duplicate button
- `apps/web/components/settings/agent-profile-page.tsx`: add a Duplicate
button to `ProfileEditorHeader` (copy icon + `t("agents:duplicate")`,
`data-testid="duplicate-profile-header"`, disabled + `aria-busy` while a
duplicate is in flight). The flow lives in the extracted
`useProfileDuplicateAction` hook
(`components/settings/agent-profile-duplicate-action.ts`, unit-tested):
a ref-based in-flight guard (two rapid clicks can never issue two
copies), then save EVERY dirty contributor via the shared settings save
coordinator (`useSettingsSaveCoordinator().saveAll` — the profile editor
AND its MCP card; `saveAll` respects each contributor's `canSave`, and the
abort toasts the blocking contributor's `invalidReason` — MCP error or
profile-name validation), POST the duplicate, merge the copy into the
store, toast `agents:duplicateProfileSuccess`, cancel any pending
navigation intent the dirty guard had blocked, and SPA-navigate via
`runWithNavigationBlockerBypassed(() => router.push(...))` — never
`window.location.assign`, so the success toast survives and the
dirty-settings blocker is already resolved by the save. The row-level
duplicate hook guards against double-clicks (per-profile in-flight set).
The profile save path (`syncAgentsToStore`) reconciles the options slice
by ID (`reconcileAgentProfileOptions`), preserving WS-delivered orphan
options exactly like the duplicate merge. The merge keeps a newer
WS-delivered orphan option (revision carried on the option as `updatedAt`)
over a stale duplicate HTTP response, matching the newer-wins rule used
when the owning agent is present.
### i18n
Add to `apps/web/src/locales/en/agents.json`:
- `"duplicate": "Duplicate"`
- `"duplicateProfile": "Duplicate profile"`
- `"duplicateProfileNamed": "Duplicate {{name}}"`
- `"duplicateProfileSuccess": "Profile duplicated"`
- `"failedToDuplicateProfile": "Failed to duplicate profile"`
Regenerate the pseudo locale (`pnpm --filter @kandev/web i18n:pseudo`). Real
locales (`zh-cn`, `pt-pt`) fall back to en; key-parity is a warning there,
missing en keys are a hard error.
### Tests (frontend)
- `apps/web/app/settings/agents/profile-list-item.test.tsx`: extend with a
case asserting the Duplicate button renders and calls `onDuplicate` with
the profile (mirroring the existing toggle tests).
- `apps/web/lib/api/domains/agent-profile-normalize.test.ts` or the actions
layer: only if an existing action-test pattern exists; otherwise the
component test plus E2E covers the contract.
## E2E
New `apps/web/e2e/tests/settings/agent-profile-duplicate.spec.ts` modeled on
`agent-profile-delete.spec.ts`:
- Create a source profile via `apiClient.createAgentProfile(agent.id,
"Dup Me", { model: agent.profiles[0].model, cli_flags: [...], command_prefix: ... })`.
- `testPage.goto("/settings/agents")`, wait for the profile list, click the
duplicate button on the "Dup Me" row (`duplicate-profile-<id>`).
- Expect a "Dup Me Copy" row to appear without reload.
- Navigate to the copy's profile page and assert the copied model/cli flag
values render.
- `finally`: delete both profiles via `apiClient.deleteAgentProfile(..., true)`.
## Implementation Waves
Execution is sequential in the primary conversation; no subagents are
authorized.
Wave 1:
- [x] [Task 01: Backend duplicate endpoint](task-01-backend-duplicate-endpoint.md)
Wave 2:
- [x] [Task 02: Frontend duplicate UI](task-02-frontend-duplicate-ui.md)
Wave 3:
- [x] [Task 03: E2E duplicate flow](task-03-duplicate-e2e.md)
## Risks
- `DuplicateAgentProfile` inserts the copy with the caller-provided enabled
state inside one transaction, unlike `CreateAgentProfile` which forces
`Enabled=true` for other callers — a store regression that forces the
duplicate enabled is pinned by `sqlite_duplicate_test.go` (disabled copy
stays disabled) and by the controller test asserting no follow-up write.
- `GetAgentProfileMcpConfig` returns different "absent" shapes across the
sqlite store (`sql.ErrNoRows`) and the shared fake store (`nil, nil`);
the controller must tolerate both.
- The list-page direct store merge and the WS `agent.profile.created`
broadcast can both insert the copy; the WS handler upserts by ID so this
is safe (verify while implementing).