kandev/docs/specs/agents/profile-duplicate.md

status, created, owner

status	created	owner
draft	2026-08-11	kandev

Duplicate an Agent Profile

Why

Profiles are the per-agent configuration unit (model, mode, config options, CLI flags, env vars, launcher prefix, auto-approve). Creating a variant of an existing profile means re-entering every field by hand today: there is no way to start from a working configuration. Users need a one-click "duplicate" that copies a profile's full configuration under a new name, so they can tweak the copy (a different model, an extra CLI flag, a sandbox launcher) without touching the source.

What

• Every profile row on the settings agents page (/settings/agents, the "Manage existing profiles by agent" list) gets a Duplicate action.
• The profile settings page (/settings/agents/<agent>/profiles/<id>) gets the same Duplicate action in its header.
• Duplicating creates a new profile that is a faithful copy of the source's configuration: name-derived new name, model, fallback model, auto-fallback, mode, config options, allow-indexing, auto-approve, CLI passthrough, CLI flags, env vars, command prefix, enabled state, and MCP config (enabled flag + servers + meta) when the source has one.
• The copy is an independent row: it gets a new ID, user_modified is set, and editing or deleting it never affects the source. No session, task, watcher, automation, or routing reference points at the copy.
• The copy is committed atomically: the row is inserted with the source's enabled state and the MCP config row is upserted in one repository transaction, so a duplicated profile inherits the source's selection state and a disabled source never becomes briefly selectable. A failure rolls back and leaves no partial copy.
• Runtime state is never copied: the copy starts idle with no pause reason, no last-run timestamp, and a zero consecutive-failure count. Office enrichment configuration (workspace, role, budget, permissions, skills, executor preference, …) is copied when present, matching the faithful-copy intent; the settings surface only lists global (non-office) profiles, so in practice those fields are empty on the rows this feature shows.
• The generated name is persisted user data, not UI copy: it is <source name> Copy (e.g. Default → Default Copy), matching the repo convention that stored names do not depend on the locale they were created in (same rule as seeded executor and repository names).

API surface

POST /api/v1/agent-profiles/:id/duplicate (interim-settings-interlock protected, like every other profile mutation):

• Request body: none. The copy name is derived server-side as <source name> Copy.
• Response 200: the new AgentProfileDTO (same shape as POST /agents/:id/profiles).
• 404 when the source profile does not exist or is soft-deleted.
• Broadcasts the existing agent.profile.created WebSocket notification so every open settings surface picks the copy up live.

The endpoint is not idempotent in the HTTP sense: each call creates one new row (there is no idempotency key), so a retried POST after a network timeout may create a second copy. Callers must treat duplicates as one-shot operations; the UI guards against double-clicks. The copy performs no reference checks because a brand-new row cannot be referenced by anything yet.

Scenarios

• GIVEN a profile named Default with model, CLI flags, env vars, and a command prefix, WHEN the user clicks Duplicate on its row in /settings/agents, THEN a new profile row Default Copy appears immediately with every configuration field equal to the source, a distinct ID, and user_modified true.
• GIVEN an MCP-capable agent profile with an MCP config (enabled with servers), WHEN it is duplicated, THEN the copy has the same MCP enabled state, servers, and meta under the new profile ID.
• GIVEN a disabled profile, WHEN it is duplicated, THEN the copy is also disabled.
• GIVEN a profile with an active session, WHEN it is duplicated, THEN the duplicate succeeds (unlike delete, no in-use checks apply) and the session keeps using the source.
• GIVEN the profile settings page of a profile, WHEN the user clicks Duplicate in the header, THEN a toast confirms the copy and the user is taken to the copy's settings page to edit it.
• GIVEN an unknown profile ID, WHEN the duplicate endpoint is called, THEN it returns 404 and creates nothing.

Out of scope

• Duplicating office workspace agents through the office UI (/office/agents): office has its own agent creation flows and permission model. This feature targets the /settings/agents profile flavor. The settings duplicate endpoint is fail-closed against office-scoped sources: a profile with a non-empty workspace_id returns 404 (existence hidden) before any MCP read or write, so the instance-level settings surface can never read or clone another workspace's configuration. Office duplication, when added, belongs on the workspace-scoped office API surface.
• Renaming after duplicate: the copy is a normal profile the user renames via the existing profile editor.
• Bulk/queue duplication, templates, or copy-paste between agents.
• Choosing the copy name in the duplicate dialog: name is derived, then edited on the copy's settings page.