Files
kandev/docs/specs/agents/profile-duplicate.md
T
2026-08-12 11:19:12 +01:00

107 lines
5.3 KiB
Markdown

---
status: draft
created: 2026-08-11
owner: 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.