agentmux_srv/server/agent_handlers/

template.rs

// Copyright 2025-2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0


use std::sync::Arc;


use crate::backend::rpc::engine::WshRpcEngine;
use crate::backend::rpc_types::{
    COMMAND_AGENT_DEF_CREATE_FROM_TEMPLATE,
    CommandAgentDefCreateFromTemplateData, AgentDefCreateFromTemplateResult,
    // Two-tier picker — Phase 2 (SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md
    // Q2 Decision Y: hide templates).
    COMMAND_AGENT_DEF_HIDE, COMMAND_AGENT_DEF_UNHIDE,
    COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES,
    CommandAgentDefHideData, AgentDefHideResult,
    COMMAND_FORK_AGENT_DEFINITION,
    COMMAND_FORK_AGENT_DEFINITION_SUGGEST,
    CommandForkAgentDefinitionSuggestData, ForkAgentDefinitionSuggestResult,
    CommandForkAgentDefinitionData, CommandListHiddenTemplatesData,
    COMMAND_RENAME_AGENT_DEFINITION_TITLE,
    CommandRenameAgentDefinitionTitleData,
};
use crate::backend::storage::{AgentDefinition, AgentContent, AgentSkill};

use super::super::AppState;

/// Resolve a definition's **fork**-lineage root by walking `parent_id`.
///
/// `parent_id` is overloaded in this schema: `agentdefcreatefromtemplate`
/// sets it to the *template's* id for every freshly-instantiated user
/// agent (see that handler below), not just `forkagentdefinition`'s actual
/// forks — so two unrelated agents both created fresh from the same
/// template share a `parent_id`, but are not forks of each other. The one
/// field that reliably distinguishes an actual fork is `branch_label`:
/// `forkagentdefinition` always sets it (non-empty); `agentdefcreatefromtemplate`
/// always leaves it empty. Walk upward only while the current node is
/// itself a fork (non-empty `branch_label`); stop at the first non-fork
/// ancestor (a template, or a first-generation user agent) — that's the
/// lineage's root for fork-counting purposes. Confirmed bug this fixes
/// (Codex's review of PR #2721, docs/specs/SPEC_AGENT_QUICK_FORK_NEW_TAB_2026_08_21.md
/// §2): the naming rule requires a flat, lineage-wide counter ("AgentX #2"
/// → "AgentX #3"), but the previous `parent_id == source_id` filter only
/// counted immediate children, so forking a fork produced "AgentX #2 #2".
fn fork_lineage_root_id(defs: &[AgentDefinition], start_id: &str) -> String {
    let mut current = start_id.to_string();
    loop {
        match defs.iter().find(|a| a.id == current) {
            Some(def) if !def.branch_label.is_empty() && !def.parent_id.is_empty() => {
                current = def.parent_id.clone();
            }
            _ => return current,
        }
    }
}

/// The definition at the root of `source`'s fork lineage (see
/// `fork_lineage_root_id`); `source` itself if the root can't be found.
fn fork_lineage_root<'a>(defs: &'a [AgentDefinition], source: &'a AgentDefinition) -> &'a AgentDefinition {
    let root_id = fork_lineage_root_id(defs, &source.id);
    defs.iter().find(|a| a.id == root_id).unwrap_or(source)
}

/// Whether a user agent (not a seeded template) already goes by `name`,
/// case-insensitively: as its name, or as its branch label, which is what a
/// renamed fork shows. Names are unique among user agents: the picker lists
/// them by name, and name-keyed registrations collide otherwise. A launched
/// agent's instance name is the store's to check (`agents_matching_name`).
fn name_taken(defs: &[AgentDefinition], name: &str) -> bool {
    defs.iter().any(|a| a.is_seeded == 0 && (a.name.eq_ignore_ascii_case(name) || a.branch_label.eq_ignore_ascii_case(name)))
}

/// `name_taken`, or the store's own name resolution finds it (slug, name,
/// or a launched agent's instance name): every name a fork could take is
/// checked against both, automatic or typed (#4746).
fn name_in_use(store: &crate::backend::storage::store::Store, defs: &[AgentDefinition], name: &str) -> bool {
    name_taken(defs, name) || store.agents_matching_name(name).map(|m| !m.is_empty()).unwrap_or(false)
}

/// Build the flat, lineage-wide "#N" auto-suggestion for forking `source`.
///
/// The name is built from the lineage **root's** name, not `source`'s own
/// (possibly already-suffixed) name — forking "AgentX #2" gives "AgentX #3",
/// not "AgentX #2 #3" (`SPEC_AGENT_NAMING_AND_ADDRESSING_HOST_LAN_WAN_2026_08_22.md`
/// §4.5). The number is one past the highest "#N" any fork in the lineage
/// already carries, or any deleted agent carried (`retired`, the store's
/// `retired_agent_names`), not a count of the live ones: a count handed a
/// deleted fork's number to the next fork, so two agents could share a name
/// over time, and live ones too while a later fork still had it
/// (REPORT_FORK_AGENT_ISOLATION_2026_10_12.md F4). A live fork's number is its
/// name's trailing " #N", whatever its prefix, so renaming the root keeps the
/// count; a deleted name counts under the root's current name, compared
/// lowercased as it was tombstoned, and under each of the root's former names
/// (`root_former`), so renaming the root after deleting forks keeps them
/// counted too. A name `taken` says is in use is skipped.
fn suggest_fork_name(
    defs: &[AgentDefinition],
    retired: &[String],
    root_former: &[String],
    source: &AgentDefinition,
    taken: impl Fn(&str) -> bool,
) -> String {
    let root = fork_lineage_root(defs, source);
    let prefix = format!("{} #", root.name);
    let suffix = |name: &str| name.rsplit_once(" #")?.1.trim().parse::<u32>().ok();
    let live = defs
        .iter()
        .filter(|a| a.is_seeded == 0 && !a.branch_label.is_empty() && fork_lineage_root_id(defs, &a.id) == root.id)
        .filter_map(|a| suffix(&a.name));
    let retired_prefixes: Vec<String> =
        std::iter::once(&root.name).chain(root_former).map(|n| format!("{n} #").to_lowercase()).collect();
    let deleted = retired.iter().filter_map(|n| {
        let n = n.to_lowercase();
        retired_prefixes.iter().find_map(|p| n.strip_prefix(p.as_str())?.trim().parse::<u32>().ok())
    });
    let highest = live.chain(deleted).max().unwrap_or(1);
    let mut n = highest.max(1) + 1;
    while taken(&format!("{prefix}{n}")) {
        n += 1;
    }
    format!("{prefix}{n}")
}

pub fn register(engine: &Arc<WshRpcEngine>, state: &AppState) {
    // agentdefcreatefromtemplate → clone a seeded template into a new
    // user-owned definition (Phase 1 two-tier picker —
    // SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md). The template stays
    // pristine; the new row carries `is_seeded = 0`. Returns the new
    // definition_id so the frontend can immediately launch.
    //
    // Validation rules:
    //  - `template_id` MUST resolve to a row with `is_seeded = 1`.
    //    Cloning a user-owned row would be confusing semantics — use
    //    the existing `forkagentdefinition` RPC for that case.
    //  - `name` non-empty, ≤200 chars, and not already taken by any
    //    `is_seeded = 0` row. Avoids collisions in the picker's
    //    "My Agents" list.
    let mstore_act = state.mstore.clone();
    let id_store_act = state.id_store.clone();
    let broker_act = state.broker.clone();
    engine.register_typed(
        COMMAND_AGENT_DEF_CREATE_FROM_TEMPLATE,
        move |cmd: CommandAgentDefCreateFromTemplateData, _ctx| {
            let mstore = mstore_act.clone();
            let id_store = id_store_act.clone();
            let broker = broker_act.clone();
            async move {
                let name = cmd.name.trim().to_string();
                if name.is_empty() {
                    return Err("agentdefcreatefromtemplate: name must be non-empty".into());
                }
                if name.chars().count() > 200 {
                    return Err(
                        "agentdefcreatefromtemplate: name must be ≤200 characters".into(),
                    );
                }

                let all = mstore
                    .agent_def_list()
                    .map_err(|e| format!("agentdefcreatefromtemplate: list: {e}"))?;
                let template = all
                    .iter()
                    .find(|a| a.id == cmd.template_id)
                    .ok_or_else(|| {
                        format!(
                            "agentdefcreatefromtemplate: template {} not found",
                            cmd.template_id
                        )
                    })?;
                if template.is_seeded != 1 {
                    return Err(format!(
                        "agentdefcreatefromtemplate: {} is not a seeded template (is_seeded={})",
                        cmd.template_id, template.is_seeded
                    ));
                }
                if name_taken(&all, &name) {
                    return Err(format!(
                        "agentdefcreatefromtemplate: an agent named {:?} already exists",
                        name
                    ));
                }

                let now = agentmux_common::time::now_ms();
                // Runtime is the user's instantiation-time choice, not a
                // template property. When supplied, the clone records it
                // (and the matching `environment`); empty falls back to
                // the template's value for back-compat with older callers.
                let chosen_agent_type = match cmd.agent_type.as_deref().unwrap_or("").trim() {
                    "host" | "container" => cmd.agent_type.as_deref().unwrap_or("").trim().to_string(),
                    _ => template.agent_type.clone(),
                };
                let chosen_environment = if chosen_agent_type == "container" {
                    "docker".to_string()
                } else {
                    "local".to_string()
                };
                // Template's EFFECTIVE provider, from the shared resolver
                // (#2594; SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1). Used for both the vendor-base-url
                // validation below and the clone's own `provider` field so
                // the two can't disagree with each other.
                let effective_provider = id_store.resolve_effective_provider_id(template);
                // Model vendor base URL: `None` (omitted) inherits the
                // template's own value (the only behavior before this
                // field existed on this RPC); `Some(url)` overrides it,
                // including `Some("")` to explicitly clear a
                // template-inherited override. Same validation `agent.define`
                // already applies — rejected unless the template's provider
                // declares `base_url_env_var`.
                let chosen_model_vendor_base_url = match &cmd.model_vendor_base_url {
                    Some(url) => {
                        crate::server::app_api::validate_vendor_base_url(&effective_provider, url)
                            .map_err(|e| format!("agentdefcreatefromtemplate: {e}"))?;
                        url.clone()
                    }
                    None => template.model_vendor_base_url.clone(),
                };
                let mut new_def = AgentDefinition {
                    id: uuid::Uuid::new_v4().to_string(),
                    // agent_def_insert derives a unique slug from the
                    // name when this is empty + collision-resolves.
                    slug: String::new(),
                    name: name.clone(),
                    icon: template.icon.clone(),
                    provider: effective_provider.clone(),
                    description: template.description.clone(),
                    // Force re-allocation of the per-agent working
                    // directory at first launch via the new slug —
                    // matches forkagentdefinition's behaviour.
                    working_directory: String::new(),
                    shell: template.shell.clone(),
                    provider_flags: template.provider_flags.clone(),
                    // Users opt in to auto-start explicitly; cloning
                    // shouldn't carry it over (mirrors fork).
                    auto_start: 0,
                    restart_on_crash: template.restart_on_crash,
                    idle_timeout_minutes: template.idle_timeout_minutes,
                    created_at: now,
                    agent_type: chosen_agent_type,
                    environment: chosen_environment,
                    agent_bus_id: String::new(),
                    is_seeded: 0,
                    accounts: String::new(),
                    parent_id: template.id.clone(),
                    branch_label: String::new(),
                    updated_at: now,
                    // New user-owned agent starts visible. Phase 2
                    // (Q2 Decision Y) — hide applies only to seeded
                    // templates, never to user-owned agents.
                    user_hidden: 0,
                    // Inherit container config from template so container-type
                    // templates propagate their image to user-cloned agents.
                    container_image: template.container_image.clone(),
                    container_volumes: template.container_volumes.clone(),
                    container_name: String::new(),
                    use_ambient_login: 0,
                    model_vendor_base_url: chosen_model_vendor_base_url,
                    auto_continue_enabled: 0,
                    memory_id: String::new(),
                    // Fail-closed default, not inherited from the template —
                    // same convention as auto_start/use_ambient_login/
                    // auto_continue_enabled above (opt-in settings reset on
                    // a fresh clone, not carried over).
                    conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
                };
                mstore
                    .agent_def_insert(&mut new_def)
                    .map_err(|e| format!("agentdefcreatefromtemplate: insert: {e}"))?;
                // Own dedicated ABF bundle, not the template's — every
                // agent has its own (ARCHITECTURE_MANDATORY_ABF_RETHINK_
                // 2026_08_14.md §3.2, "strong reading").
                mstore.agent_def_provision_and_bind_bundle(&id_store, &mut new_def, now);
                // After the own bundle exists, so a pick of it is dropped.
                if let Some(bundle_ids) = cmd.bundle_ids.as_deref().filter(|ids| !ids.is_empty()) {
                    mstore
                        .agent_bundles_set(&new_def.id, bundle_ids)
                        .map_err(|e| format!("agentdefcreatefromtemplate: bundles: {e}"))?;
                }

                broker.publish_event::<crate::backend::mps_events::AgentsChanged>(&(), vec![], 0);

                let resp = AgentDefCreateFromTemplateResult {
                    definition_id: new_def.id.clone(),
                    identity_id: cmd.identity_id.unwrap_or_default(),
                    memory_id: cmd.memory_id.unwrap_or_default(),
                    slug: new_def.slug.clone(),
                };
                tracing::info!(
                    template_id = %cmd.template_id,
                    new_definition_id = %new_def.id,
                    new_name = %new_def.name,
                    "agentdefcreatefromtemplate: cloned template into user agent"
                );
                Ok(resp)
            }
        },
    );

    // agentdefhide → set user_hidden = 1 on a seeded template, so it
    // disappears from the picker's "+ New from template" tier. Phase 2
    // (Q2 Decision Y) of SPEC_AGENT_PICKER_TWO_TIER_2026_05_24.md.
    //
    // Validation:
    //  - `definition_id` MUST exist. Missing → returns `{ ok: false }`.
    //  - The row MUST be a seeded template (`is_seeded = 1`). User-owned
    //    rows reject with a hard error — they have their own delete path
    //    and a hide flag on them would be misleading.
    //
    // Broadcasts `agents:changed` so the picker refetches and the card
    // disappears (existing list query already excludes hidden by default).
    let mstore_hide = state.mstore.clone();
    let broker_hide = state.broker.clone();
    // Registered through `register_typed` (rather than `register_handler`)
    // so this command's request/response pair lands in the engine's
    // `RpcSchema` — the mapping the frontend's bindings will be generated
    // from. See `backend/rpc/schema.rs`. Behaviour is unchanged: the
    // deserialize-in / serialize-out steps this body used to perform are
    // exactly what the wrapper now does.
    engine.register_typed(
        COMMAND_AGENT_DEF_HIDE,
        move |cmd: CommandAgentDefHideData, _ctx| {
            let mstore = mstore_hide.clone();
            let broker = broker_hide.clone();
            async move {
                let ok = mstore
                    .agent_def_set_hidden(&cmd.definition_id, true)
                    .map_err(|e| format!("agentdefhide: {e}"))?;
                if ok {
                    broker.publish_event::<crate::backend::mps_events::AgentsChanged>(&(), vec![], 0);
                    tracing::info!(
                        definition_id = %cmd.definition_id,
                        "agentdefhide: hid template"
                    );
                }
                Ok(AgentDefHideResult { ok })
            }
        },
    );

    // agentdefunhide → set user_hidden = 0 on a seeded template,
    // bringing it back into the picker. Same validation + broadcast as
    // agentdefhide. Phase 2 of the two-tier picker spec.
    let mstore_unhide = state.mstore.clone();
    let broker_unhide = state.broker.clone();
    engine.register_typed(
        COMMAND_AGENT_DEF_UNHIDE,
        move |cmd: CommandAgentDefHideData, _ctx| {
            let mstore = mstore_unhide.clone();
            let broker = broker_unhide.clone();
            async move {
                let ok = mstore
                    .agent_def_set_hidden(&cmd.definition_id, false)
                    .map_err(|e| format!("agentdefunhide: {e}"))?;
                if ok {
                    broker.publish_event::<crate::backend::mps_events::AgentsChanged>(&(), vec![], 0);
                    tracing::info!(
                        definition_id = %cmd.definition_id,
                        "agentdefunhide: unhid template"
                    );
                }
                Ok(AgentDefHideResult { ok })
            }
        },
    );

    // agentdeflisthiddentemplates → templates the user has hidden
    // (is_seeded = 1 AND user_hidden = 1). Used by the settings panel
    // to render the unhide list. The picker proper never calls this —
    // it uses `listagents` with the default-filter-out behaviour.
    let mstore_lh = state.mstore.clone();
    engine.register_typed(
        COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES,
        // `Option<_>`, not the bare struct — see the type's own comment:
        // it is what makes both no-argument encodings (`{}` and `null`)
        // deserialize, which a typed registration otherwise cannot do.
        move |_req: Option<CommandListHiddenTemplatesData>, _ctx| {
            let mstore = mstore_lh.clone();
            async move {
                let agents = mstore
                    .agent_def_list()
                    .map_err(|e| format!("agentdeflisthiddentemplates: {e}"))?;
                let hidden: Vec<_> = agents
                    .into_iter()
                    .filter(|a| a.is_seeded == 1 && a.user_hidden == 1)
                    .collect();
                Ok(hidden)
            }
        },
    );

    // ---- Definition fork ----

    let mstore = state.mstore.clone();
    let id_store = state.id_store.clone();
    let broker = state.broker.clone();
    engine.register_typed(
        COMMAND_FORK_AGENT_DEFINITION,
        move |cmd: CommandForkAgentDefinitionData, _ctx| {
            let mstore = mstore.clone();
            let id_store = id_store.clone();
            let broker = broker.clone();
            async move {

                // Find the source definition by id.
                let all_defs = mstore
                    .agent_def_list()
                    .map_err(|e| format!("forkagentdefinition: {e}"))?;
                let source = all_defs
                    .iter()
                    .find(|a| a.id == cmd.source_id)
                    .cloned()
                    .ok_or_else(|| format!("forkagentdefinition: source not found: {}", cmd.source_id))?;

                // Build a new definition that shares the source's content but
                // has a fresh id/slug and records the lineage. Seed-bit is
                // cleared — forks are always user-owned, not built-in.
                let now = agentmux_common::time::now_ms();

                // branch_label is the fork's full display name when provided.
                // When empty, auto-generate a flat, lineage-wide "Name #N"
                // (see suggest_fork_name's doc comment).
                let fork_name = if cmd.branch_label.is_empty() {
                    let root_former = mstore.agent_former_names(&fork_lineage_root(&all_defs, &source).id).unwrap_or_default();
                    suggest_fork_name(&all_defs, &mstore.retired_agent_names().unwrap_or_default(), &root_former, &source, |n| {
                        name_in_use(&mstore, &all_defs, n)
                    })
                } else {
                    cmd.branch_label.clone()
                };
                let branch_label = if cmd.branch_label.is_empty() {
                    fork_name.clone()
                } else {
                    cmd.branch_label.clone()
                };
                if !cmd.branch_label.is_empty() && name_in_use(&mstore, &all_defs, &fork_name) {
                    return Err(format!("forkagentdefinition: an agent named {fork_name:?} already exists"));
                }
                // The root's slug and this fork's label: never the source's
                // slug, which chained every generation (`loap-loap-2-loap-3`).
                let root = fork_lineage_root(&all_defs, &source);
                let fork_slug = agentmux_common::slug::fork_slug(&root.slug, &root.name, &branch_label);
                // Source's EFFECTIVE provider, from the shared resolver
                // (#2594; same as the create-from-template clone site).
                let effective_provider = id_store.resolve_effective_provider_id(&source);
                let mut fork = AgentDefinition {
                    id: uuid::Uuid::new_v4().to_string(),
                    // Empty slug → agent_def_insert derives + resolves collisions.
                    slug: fork_slug,
                    name: fork_name,
                    icon: source.icon.clone(),
                    provider: effective_provider,
                    description: source.description.clone(),
                    working_directory: String::new(), // force re-resolve via agentmuxHome()
                    shell: source.shell.clone(),
                    provider_flags: source.provider_flags.clone(),
                    auto_start: 0, // forks don't auto-start; explicit launch only
                    restart_on_crash: source.restart_on_crash,
                    idle_timeout_minutes: source.idle_timeout_minutes,
                    created_at: now,
                    agent_type: source.agent_type.clone(),
                    environment: source.environment.clone(),
                    agent_bus_id: String::new(), // fresh bus id so broadcasts don't cross
                    is_seeded: 0,
                    accounts: String::new(),
                    parent_id: source.id.clone(),
                    branch_label: branch_label.clone(),
                    updated_at: now,
                    user_hidden: 0,
                    // Forks inherit container config from source so forked container agents
                    // retain their image and volumes.
                    container_image: source.container_image.clone(),
                    container_volumes: source.container_volumes.clone(),
                    container_name: String::new(),
                    use_ambient_login: 0,
                    model_vendor_base_url: source.model_vendor_base_url.clone(),
                    auto_continue_enabled: 0,
                    memory_id: String::new(),
                    // Fail-closed default, not inherited from source — same
                    // convention as use_ambient_login/auto_continue_enabled
                    // above (opt-in settings reset on a fork, not carried
                    // over, even though other config like container image
                    // and model vendor IS inherited).
                    conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
                };
                mstore
                    .agent_def_insert(&mut fork)
                    .map_err(|e| format!("forkagentdefinition: {e}"))?;
                // Own dedicated ABF bundle, not the source's — same "every
                // agent has its own" rule as the template-clone path above.
                mstore.agent_def_provision_and_bind_bundle(&id_store, &mut fork, now);

                // Deep-copy content blobs + skills from source. Cascade foreign
                // keys on the source are unaffected — we're copying out, not
                // moving.
                let source_contents = mstore
                    .agent_content_get_all(&source.id)
                    .map_err(|e| format!("forkagentdefinition content: {e}"))?;
                for c in source_contents {
                    let new_content = AgentContent {
                        agent_id: fork.id.clone(),
                        content_type: c.content_type,
                        content: c.content,
                        updated_at: now,
                    };
                    mstore
                        .agent_content_set(&new_content)
                        .map_err(|e| format!("forkagentdefinition content: {e}"))?;
                }
                let source_skills = mstore
                    .agent_skill_list(&source.id)
                    .map_err(|e| format!("forkagentdefinition skills: {e}"))?;
                for s in source_skills {
                    let new_skill = AgentSkill {
                        id: uuid::Uuid::new_v4().to_string(),
                        agent_id: fork.id.clone(),
                        name: s.name,
                        trigger: s.trigger,
                        skill_type: s.skill_type,
                        description: s.description,
                        content: s.content,
                        created_at: now,
                    };
                    mstore
                        .agent_skill_insert(&new_skill)
                        .map_err(|e| format!("forkagentdefinition skill: {e}"))?;
                }

                broker.publish_event::<crate::backend::mps_events::AgentsChanged>(&(), vec![], 0);

                Ok(fork)
            }
        },
    );

    // ---- Definition fork suggest (read-only — no mutation) ----

    let mstore_sug = state.mstore.clone();
    engine.register_typed(
        COMMAND_FORK_AGENT_DEFINITION_SUGGEST,
        move |cmd: CommandForkAgentDefinitionSuggestData, _ctx| {
            let mstore = mstore_sug.clone();
            async move {
                let all = mstore
                    .agent_def_list()
                    .map_err(|e| format!("forkagentdefinitionsuggest: {e}"))?;
                let source = all
                    .iter()
                    .find(|a| a.id == cmd.source_id)
                    .ok_or_else(|| format!("forkagentdefinitionsuggest: source not found: {}", cmd.source_id))?;

                let root_former = mstore.agent_former_names(&fork_lineage_root(&all, source).id).unwrap_or_default();
                let suggested_label = suggest_fork_name(&all, &mstore.retired_agent_names().unwrap_or_default(), &root_former, source, |n| {
                    name_in_use(&mstore, &all, n)
                });

                Ok(ForkAgentDefinitionSuggestResult { suggested_label })
            }
        },
    );

    // ---- Rename a fork/agent tab's displayed title ----
    //
    // Deliberately separate from `updateagent`, which preserves
    // `branch_label` unconditionally (core.rs: "parent_id + branch_label
    // describe provenance and are immutable post-insert"). That contract
    // stays true for every OTHER caller of `updateagent` — this handler is
    // the one narrow, explicit path that's allowed to change it, and only
    // the field `fork-set.ts`'s `titleOf()` actually displays: `branch_label`
    // when the row already has one (a fork), else `name` (a lineage root).
    // See SPEC_PANE_TAB_STRIP_COMPACT_SIZING_AND_RENAME_2026_07_22.md §4.
    let mstore_rn = state.mstore.clone();
    let broker_rn = state.broker.clone();
    engine.register_typed(
        COMMAND_RENAME_AGENT_DEFINITION_TITLE,
        move |cmd: CommandRenameAgentDefinitionTitleData, _ctx| {
            let mstore = mstore_rn.clone();
            let broker = broker_rn.clone();
            async move {
                let title = cmd.title.trim();
                if title.is_empty() {
                    return Err("renameagentdefinitiontitle: title must not be empty".to_string());
                }

                let all = mstore
                    .agent_def_list()
                    .map_err(|e| format!("renameagentdefinitiontitle: {e}"))?;
                let old = all
                    .iter()
                    .find(|a| a.id == cmd.id)
                    .ok_or_else(|| format!("renameagentdefinitiontitle: agent {} not found", cmd.id))?;

                let mut updated = old.clone();
                if !updated.branch_label.is_empty() {
                    updated.branch_label = title.to_string();
                } else {
                    updated.name = title.to_string();
                }

                let found = mstore
                    .agent_def_update(&mut updated)
                    .map_err(|e| format!("renameagentdefinitiontitle: {e}"))?;
                if !found {
                    return Err(format!("renameagentdefinitiontitle: agent {} not found", cmd.id));
                }

                // The fields above are what the pane tab strip's `titleOf()`
                // reads. "My Agents" rows render `instance_name` instead, so
                // without this a rename from the picker closed its editor,
                // refetched, and redisplayed the OLD name (codex P1 on
                // PR #3262). See `Store::instance_rename` for why it's
                // scoped to rows that already carry an `instance_name`.
                //
                // This also applies to the tab-strip rename, deliberately:
                // since the agent-concept consolidation a fork tab and its
                // picker row are ONE agent row, so letting the two names
                // drift apart is the confusing outcome, not the safe one.
                // Best-effort — the title change already landed, and a
                // display-name mirror failing is not a failed rename.
                if let Err(e) = mstore.instance_rename(&cmd.id, title) {
                    tracing::warn!(
                        agent_id = %cmd.id, error = %e,
                        "renameagentdefinitiontitle: display name not updated; \
                         the picker row may keep showing the old name"
                    );
                }

                broker.publish_event::<crate::backend::mps_events::AgentsChanged>(&(), vec![], 0);

                Ok(updated)
            }
        },
    );

}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::backend::rpc_types::RpcMessage;
    use crate::backend::storage::bundles::Bundle;
    use crate::server::tests::test_state;

    fn seed_bundle(state: &AppState, id: &str, provider: &str) {
        let bundle = Bundle {
            id: id.to_string(),
            name: "Bundle".to_string(),
            description: String::new(),
            is_blank: false,
            is_global: false,
            provider: provider.to_string(),
            model: String::new(),
            instructions: String::new(),
            instructions_by_provider: "{}".to_string(),
            context_files: "[]".to_string(),
            mcp_servers: "[]".to_string(),
            skills: "[]".to_string(),
            sort_order: 0,
            created_at: 0,
            updated_at: 0,
            is_system: false,
        };
        state.id_store.bundle_upsert(&bundle).unwrap();
    }

    // The template says "codex"; its bound bundle, from before bundles
    // stopped carrying a harness, says "claude". The agent owns its harness
    // (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1), so a clone or fork
    // carries "codex".
    fn seed_drifted_template(state: &AppState, def_id: &str, bundle_id: &str) {
        let mut def = AgentDefinition {
            conversation_visibility: crate::backend::storage::agents::default_conversation_visibility(),
            id: def_id.to_string(),
            slug: String::new(),
            name: "Drifted Template".to_string(),
            icon: String::new(),
            provider: "codex".to_string(),
            description: String::new(),
            working_directory: String::new(),
            shell: String::new(),
            provider_flags: String::new(),
            auto_start: 0,
            restart_on_crash: 0,
            idle_timeout_minutes: 0,
            created_at: 0,
            agent_type: "host".to_string(),
            environment: String::new(),
            agent_bus_id: String::new(),
            is_seeded: 1,
            accounts: String::new(),
            parent_id: String::new(),
            branch_label: String::new(),
            updated_at: 0,
            user_hidden: 0,
            container_image: String::new(),
            container_volumes: "[]".to_string(),
            container_name: String::new(),
            use_ambient_login: 0,
            auto_continue_enabled: 0,
            model_vendor_base_url: String::new(),
            memory_id: bundle_id.to_string(),
        };
        state.mstore.agent_def_insert(&mut def).unwrap();
    }

    /// Both commands migrated to `register_typed` in this PR are recorded
    /// in the engine's schema with their exact type names — the property
    /// the RPC codegen plan depends on (`register_typed_records_each_command_
    /// request_and_response_type` in agent_handlers/mod.rs covers the first
    /// two migrated commands; this covers the second batch).
    #[tokio::test]
    async fn register_typed_records_the_second_batch_of_migrated_commands() {
        let state = test_state();
        let (engine, _rx) = WshRpcEngine::new();
        register(&engine, &state);
        let schema = engine.schema_json();
        let rows = schema.as_array().unwrap();
        let find = |cmd: &str| {
            rows.iter()
                .find(|r| r["command"] == cmd)
                .unwrap_or_else(|| panic!("{cmd} missing from the schema"))
        };
        let a = find(COMMAND_AGENT_DEF_CREATE_FROM_TEMPLATE);
        assert_eq!(a["requestName"], "CommandAgentDefCreateFromTemplateData");
        assert_eq!(a["responseName"], "AgentDefCreateFromTemplateResult");
        let f = find(COMMAND_FORK_AGENT_DEFINITION_SUGGEST);
        assert_eq!(f["requestName"], "CommandForkAgentDefinitionSuggestData");
        assert_eq!(f["responseName"], "ForkAgentDefinitionSuggestResult");
        // The remaining three, migrated in the agent-template slice. Their
        // responses are the storage-level `AgentDefinition`, which is why they
        // waited for that type to be generated.
        let r = find(COMMAND_RENAME_AGENT_DEFINITION_TITLE);
        assert_eq!(r["requestName"], "CommandRenameAgentDefinitionTitleData");
        assert_eq!(r["responseName"], "AgentDefinition");
        let fk = find(COMMAND_FORK_AGENT_DEFINITION);
        assert_eq!(fk["requestName"], "CommandForkAgentDefinitionData");
        assert_eq!(fk["responseName"], "AgentDefinition");

        // `Vec<T>` keeps its full path — truncating at the last `::` would
        // yield `AgentDefinition>`, which names nothing — so match on the
        // element type rather than on an exact string.
        let lh = find(COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES);
        let lh_req = lh["requestName"].as_str().unwrap_or_default();
        assert!(
            lh_req.starts_with("core::option::Option<")
                && lh_req.contains("CommandListHiddenTemplatesData"),
            "agentdeflisthiddentemplates takes Option<CommandListHiddenTemplatesData>              so both no-argument encodings deserialize, got {lh_req:?}",
        );
        let lh_resp = lh["responseName"].as_str().unwrap_or_default();
        assert!(
            lh_resp.starts_with("alloc::vec::Vec<") && lh_resp.contains("AgentDefinition"),
            "agentdeflisthiddentemplates should answer Vec<AgentDefinition>, got {lh_resp:?}",
        );
        assert!(
            !lh_resp.contains("serde_json::Value"),
            "hand-serializing would record Value and leave this endpoint outside              the drift net; got {lh_resp:?}",
        );
    }

    /// `agentdeflisthiddentemplates` takes no argument, and the RPC client
    /// sends `{}` for that. A unit `Req` would reject every one of those
    /// calls, because serde deserializes `()` only from JSON `null` — hence
    /// the empty struct. This is the `bookmarks.list` failure re-tested at
    /// the one place in this slice that could reproduce it.
    #[tokio::test]
    async fn listhiddentemplates_accepts_the_empty_object_the_stub_sends() {
        let state = test_state();
        let (engine, mut rx) = WshRpcEngine::new();
        register(&engine, &state);

        for payload in [serde_json::json!({}), serde_json::Value::Null] {
            engine.handle_message(RpcMessage {
                command: COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES.to_string(),
                reqid: format!("req-{payload}"),
                data: Some(payload.clone()),
                ..Default::default()
            });
            let resp = tokio::time::timeout(std::time::Duration::from_secs(2), rx.recv())
                .await
                .unwrap()
                .unwrap();
            assert!(
                resp.error.is_empty(),
                "{payload} should be accepted, got error: {}",
                resp.error,
            );
            let rows: Vec<AgentDefinition> =
                serde_json::from_value(resp.data.expect("expected result data")).unwrap();
            assert!(rows.is_empty(), "nothing is hidden in a fresh store");
        }
    }

    /// The four payload-ignoring agent commands all take `Option<Req>`, so a
    /// client that omits `data` entirely -- which the server turns into
    /// `Value::Null` -- is accepted rather than answered with a deserialize
    /// error. One test rather than four: the failure is a property of the
    /// registration shape, not of any one command.
    #[tokio::test]
    async fn no_argument_commands_accept_a_null_body() {
        use crate::backend::rpc_types::{
            COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES, COMMAND_CONTAINER_RUNTIME_AVAILABLE,
        };

        let state = test_state();
        let (engine, mut rx) = WshRpcEngine::new();
        register(&engine, &state);
        crate::server::agent_handlers::core::register(&engine, &state);

        for cmd in [
            COMMAND_AGENT_DEF_LIST_HIDDEN_TEMPLATES,
            COMMAND_CONTAINER_RUNTIME_AVAILABLE,
        ] {
            engine.handle_message(RpcMessage {
                command: cmd.to_string(),
                reqid: format!("req-{cmd}"),
                data: Some(serde_json::Value::Null),
                ..Default::default()
            });
            let resp = tokio::time::timeout(std::time::Duration::from_secs(2), rx.recv())
                .await
                .unwrap()
                .unwrap();
            assert!(
                resp.error.is_empty(),
                "{cmd} should accept a null body, got error: {}",
                resp.error,
            );
        }
    }

    /// `branch_label` is `#[serde(default)]`, so a caller may omit it — the
    /// generated TS cannot say so (ts-rs marks a non-`Option` field required),
    /// which is why the stub derives `ForkAgentDefinitionInput` rather than
    /// using the generated type directly. Pin the server half of that claim:
    /// if the `default` is ever dropped, the derived TS type becomes a lie.
    #[test]
    fn fork_request_accepts_a_missing_branch_label() {
        let cmd: CommandForkAgentDefinitionData =
            serde_json::from_value(serde_json::json!({ "source_id": "abc" }))
                .expect("branch_label is serde(default) and may be omitted");
        assert_eq!(cmd.source_id, "abc");
        assert_eq!(cmd.branch_label, "", "an omitted branch_label defaults to empty");
    }

    #[tokio::test]
    async fn agentdefcreatefromtemplate_carries_the_templates_own_provider() {
        let state = test_state();
        seed_bundle(&state, "bundle-claude", "claude");
        seed_drifted_template(&state, "tpl-1", "bundle-claude");

        let (engine, mut output_rx) = WshRpcEngine::new();
        register(&engine, &state);

        engine.handle_message(RpcMessage {
            command: COMMAND_AGENT_DEF_CREATE_FROM_TEMPLATE.to_string(),
            reqid: "req-1".to_string(),
            data: Some(serde_json::json!({
                "template_id": "tpl-1",
                "name": "My Clone",
            })),
            ..Default::default()
        });
        let resp = tokio::time::timeout(std::time::Duration::from_secs(2), output_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp.error.is_empty(), "unexpected error: {}", resp.error);
        let result: AgentDefCreateFromTemplateResult =
            serde_json::from_value(resp.data.expect("expected result data")).unwrap();

        let cloned = state
            .mstore
            .agent_def_get(&result.definition_id)
            .unwrap()
            .unwrap();
        assert_eq!(
            cloned.provider, "codex",
            "the agent owns its harness; the bundle's provider is a hint (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1)"
        );
    }

    #[tokio::test]
    async fn forkagentdefinition_carries_the_sources_own_provider() {
        let state = test_state();
        seed_bundle(&state, "bundle-claude", "claude");
        seed_drifted_template(&state, "src-1", "bundle-claude");

        let (engine, mut output_rx) = WshRpcEngine::new();
        register(&engine, &state);

        engine.handle_message(RpcMessage {
            command: COMMAND_FORK_AGENT_DEFINITION.to_string(),
            reqid: "req-1".to_string(),
            data: Some(serde_json::json!({
                "source_id": "src-1",
                "branch_label": "",
            })),
            ..Default::default()
        });
        let resp = tokio::time::timeout(std::time::Duration::from_secs(2), output_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp.error.is_empty(), "unexpected error: {}", resp.error);
        let fork: AgentDefinition =
            serde_json::from_value(resp.data.expect("expected result data")).unwrap();

        assert_eq!(
            fork.provider, "codex",
            "the agent owns its harness; the bundle's provider is a hint (SPEC_AGENT_BUNDLE_FORMAT_V0_3_2026_10_05.md §3.1)"
        );
    }

    // #2721 Phase 1 (Codex's review) — the auto-suggested name must be a
    // flat, lineage-wide counter off the ROOT's name, not the immediate
    // parent's (possibly already-suffixed) name. Forking a fork used to
    // produce "Drifted Template #2 #2" (immediate-parent-only count) or
    // even "Drifted Template #2 #3" (root-based count, but still built off
    // the parent's own name) — the correct result is the flat
    // "Drifted Template #3".
    #[tokio::test]
    async fn forking_a_fork_produces_a_flat_lineage_wide_name() {
        let state = test_state();
        seed_bundle(&state, "bundle-claude", "claude");
        seed_drifted_template(&state, "root-1", "bundle-claude");

        let (engine, mut output_rx) = WshRpcEngine::new();
        register(&engine, &state);

        let fork_once = |engine: &Arc<WshRpcEngine>, source_id: &str| {
            engine.handle_message(RpcMessage {
                command: COMMAND_FORK_AGENT_DEFINITION.to_string(),
                reqid: "req".to_string(),
                data: Some(serde_json::json!({ "source_id": source_id, "branch_label": "" })),
                ..Default::default()
            });
        };

        fork_once(&engine, "root-1");
        let resp1 = tokio::time::timeout(std::time::Duration::from_secs(2), output_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp1.error.is_empty(), "unexpected error: {}", resp1.error);
        let fork1: AgentDefinition = serde_json::from_value(resp1.data.expect("expected result data")).unwrap();
        assert_eq!(fork1.name, "Drifted Template #2");

        fork_once(&engine, &fork1.id);
        let resp2 = tokio::time::timeout(std::time::Duration::from_secs(2), output_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp2.error.is_empty(), "unexpected error: {}", resp2.error);
        let fork2: AgentDefinition = serde_json::from_value(resp2.data.expect("expected result data")).unwrap();
        assert_eq!(
            fork2.name, "Drifted Template #3",
            "forking a fork must produce a flat, lineage-wide name — not \"#2 #2\" (immediate-parent-only \
             count) or \"#2 #3\" (root-based count off the parent's own already-suffixed name)"
        );
        // Slugs are flat too: the root's slug and the fork's own label, not
        // the source's slug (`drifted-template-drifted-template-2-…`, F4).
        assert_eq!(fork1.slug, "drifted-template-2");
        assert_eq!(fork2.slug, "drifted-template-3");

        // The suggest RPC (used to preview the name before the user
        // confirms) must agree with what an actual fork would produce.
        engine.handle_message(RpcMessage {
            command: COMMAND_FORK_AGENT_DEFINITION_SUGGEST.to_string(),
            reqid: "req-suggest".to_string(),
            data: Some(serde_json::json!({ "source_id": fork2.id })),
            ..Default::default()
        });
        let resp3 = tokio::time::timeout(std::time::Duration::from_secs(2), output_rx.recv())
            .await
            .unwrap()
            .unwrap();
        assert!(resp3.error.is_empty(), "unexpected error: {}", resp3.error);
        let suggestion: ForkAgentDefinitionSuggestResult =
            serde_json::from_value(resp3.data.expect("expected result data")).unwrap();
        assert_eq!(suggestion.suggested_label, "Drifted Template #4");
    }

    /// A user agent and its forks, as `suggest_fork_name` sees them.
    fn lineage(forks: &[(&str, &str)]) -> Vec<AgentDefinition> {
        let mut root = crate::backend::storage::agents::test_agent_def("root", "Loap", "claude", "host", 1, "");
        root.is_seeded = 0;
        let mut defs = vec![root];
        for (id, name) in forks {
            let mut d = crate::backend::storage::agents::test_agent_def(id, name, "claude", "host", 2, "");
            d.is_seeded = 0;
            d.parent_id = "root".to_string();
            d.branch_label = name.to_string();
            defs.push(d);
        }
        defs
    }

    /// REPORT_FORK_AGENT_ISOLATION_2026_10_12.md F4: after "Loap #2" is
    /// deleted, a count gave the next fork "#3" while "Loap #3" still lived.
    #[test]
    fn a_fork_number_is_one_past_the_highest_not_a_count() {
        let defs = lineage(&[("f3", "Loap #3")]);
        assert_eq!(suggest_fork_name(&defs, &[], &[], &defs[0], |n| name_taken(&defs, n)), "Loap #4");
        let first = lineage(&[]);
        assert_eq!(suggest_fork_name(&first, &[], &[], &first[0], |n| name_taken(&first, n)), "Loap #2");
    }

    /// A suggested name another agent already has is skipped.
    #[test]
    fn a_fork_name_some_other_agent_has_is_skipped() {
        let mut defs = lineage(&[]);
        let mut other = crate::backend::storage::agents::test_agent_def("other", "Loap #2", "claude", "host", 3, "");
        other.is_seeded = 0;
        defs.push(other);
        assert_eq!(suggest_fork_name(&defs, &[], &[], &defs[0], |n| name_taken(&defs, n)), "Loap #3");
        assert!(name_taken(&defs, "loap #2"), "case-insensitively");
    }

    /// Deleting the highest fork must not hand its number out again (#4746).
    /// Deleted agents' names are tombstoned, lowercased.
    #[test]
    fn a_deleted_forks_number_is_not_handed_out_again() {
        let defs = lineage(&[]);
        assert_eq!(suggest_fork_name(&defs, &["loap #2".to_string()], &[], &defs[0], |n| name_taken(&defs, n)), "Loap #3");
    }

    /// Renaming the root keeps the count: forks keep their old prefix, and
    /// their trailing number still counts (#4746).
    #[test]
    fn renaming_the_root_keeps_the_fork_count() {
        let mut defs = lineage(&[("f2", "Loap #2"), ("f3", "Loap #3")]);
        defs[0].name = "Foo".to_string();
        assert_eq!(suggest_fork_name(&defs, &[], &[], &defs[0], |n| name_taken(&defs, n)), "Foo #4");
    }

    /// A deleted non-ASCII name is tombstoned lowercased, and still counts (#4746).
    #[test]
    fn a_deleted_non_ascii_forks_number_counts() {
        let mut defs = lineage(&[]);
        defs[0].name = "Ägent".to_string();
        assert_eq!(
            suggest_fork_name(&defs, &["ägent #2".to_string()], &[], &defs[0], |n| name_taken(&defs, n)),
            "Ägent #3"
        );
    }

    /// A fork deleted before the root was renamed still counts, through the
    /// root's former name (#4746).
    #[test]
    fn a_fork_deleted_before_the_root_was_renamed_still_counts() {
        let mut defs = lineage(&[]);
        defs[0].name = "Foo".to_string();
        let retired = ["loap #2".to_string()];
        let former = ["Loap".to_string()];
        assert_eq!(suggest_fork_name(&defs, &retired, &former, &defs[0], |n| name_taken(&defs, n)), "Foo #3");
    }

    /// An automatic name another agent has in a way only the store knows (a
    /// launched agent's instance name) is skipped too (#4746).
    #[test]
    fn an_automatic_name_the_taken_check_rejects_is_skipped() {
        let defs = lineage(&[]);
        assert_eq!(suggest_fork_name(&defs, &[], &[], &defs[0], |n| n == "Loap #2"), "Loap #3");
    }

    /// A renamed fork shows its branch label, which a new fork must not take
    /// (#4746).
    #[test]
    fn a_renamed_forks_label_is_taken() {
        let mut defs = lineage(&[("f2", "Loap #2")]);
        defs[1].branch_label = "Experiment".to_string();
        assert!(name_taken(&defs, "experiment"));
    }
}