supercode_harness/

profiles_control.rs

//! ORCH-21 — the `profile` noun at the CONTROLLED tier: create and delete a
//! routed config home through the HARNESS'S OWN verb, with supercode as the
//! uniform client.
//!
//! Charter (`docs/plans/orchestration-domain-11-2026-09-02.md` §0.4):
//! **supercode never owns a harness's config plane.** It makes no directory,
//! writes no config file, and removes nothing itself. Each verb below is a
//! subprocess of the harness's own CLI, run in the harness's own home:
//!
//! * **Hermes** — `hermes profile create <name>` / `hermes profile delete
//!   --yes <name>` with `HERMES_HOME` pointing at the ROOT home the caller
//!   addressed (`HERMES_HOME/profiles/<name>` is what the verb makes;
//!   upstream `hermes_constants.get_default_hermes_root` derives the profiles
//!   root from that variable). `--clone-from` carries the uniform `from`.
//! * **OpenClaw** — `openclaw agents add <id> --workspace <dir>
//!   --non-interactive --json` / `openclaw agents delete <id> --force --json`,
//!   pointed at the caller's state dir through openclaw's own environment
//!   contract. At the pin these edit `openclaw.json` directly (`agents.list`);
//!   `agents delete` additionally offers the change to a RUNNING gateway when
//!   one is reachable, resolving that endpoint itself — neither verb takes a
//!   `--url`/`--token` flag, so supercode passes no credential here.
//! * **The orchestrator** — its own package (ORC-13). A profile IS a folder
//!   whose files are the model's serialization (`docs/ORCHESTRATOR-IR.md`
//!   §6), so `create` is a new folder record followed by the package's own
//!   `save()`, and `delete` removes the record and has the daemon RENAME the
//!   folder into `profiles/.trash/<name>-<stamp>/` — nothing is ever
//!   unlinked. Both go through [`crate::orchestrator_door`]: the daemon's
//!   socket while it is up, `node bin/orchestrator.mjs profiles.create|delete`
//!   when it is down. supercode still writes no file of that folder itself.
//! * **Codex** — refused. A Codex profile is a `[profiles.<name>]` TABLE that
//!   a human (or a tool) authors in `$CODEX_HOME/config.toml`; Codex publishes
//!   no `codex profile create|delete` verb, so supercode names that door
//!   rather than editing another harness's config file behind its back.
//! * **supercode presets** — refused. A preset is compiled-in CODE
//!   ([`crate::presets::RESERVED_PRESET_NAMES`]), not a directory a verb can
//!   make.
//!
//! The three tier rules inherited from ORCH-18 hold here unchanged:
//!
//! 1. **The harness's answer is the answer.** After the verb exits 0 the row
//!    is re-read through the ORCH-10 loader ([`crate::profiles`]) and
//!    returned. A non-zero exit surfaces the harness's own stderr as the
//!    error — never a silent success, never a supercode-invented row.
//! 2. **The command is narrated.** Every outcome carries `ran`: the exact
//!    argv that was executed, credentials redacted.
//! 3. **A verb the harness does not publish is refused**
//!    ([`ProfileControlError::Unsupported`] → `UnsupportedAction`), never
//!    faked.
//!
//! One deliberate flag supercode does NOT let the harness default: nothing
//! here writes outside the home the caller addressed. `hermes profile create`
//! also drops a wrapper script into `~/.local/bin/<name>` (upstream
//! `profiles.py::_get_wrapper_dir`, which ignores `HERMES_HOME`), so the
//! non-interactive client form passes `--no-alias` — a programmatic
//! `profiles.create` against an isolated home must not install an executable
//! on the caller's PATH. The flag is in `ran`, so the choice is visible.

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::harness_command::HarnessCommand;
use crate::profiles::ProfileRow;
use crate::{HarnessHomes, HarnessId};

/// Harnesses whose profiles supercode can MUTATE through their own CLI verb.
/// Strictly narrower than [`crate::profiles::PROFILE_HARNESSES`]: Codex
/// profiles and supercode presets are readable but not controllable.
pub const CONTROLLED_PROFILE_HARNESSES: &[&str] = &[
    HarnessId::HERMES,
    HarnessId::OPENCLAW,
    HarnessId::ORCHESTRATOR,
];

/// Why Codex refuses `profiles.create` / `profiles.delete`.
pub const CODEX_REFUSAL: &str =
    "codex profiles are file-authored: a profile IS a `[profiles.<name>]` table in \
     `$CODEX_HOME/config.toml`, created by adding that table and deleted by removing it. Codex \
     publishes no `codex profile create|delete` verb a client can call, so supercode names the \
     door rather than editing another harness's config file behind its back";

/// Why supercode's own presets refuse the same two verbs.
pub const PRESET_REFUSAL: &str =
    "a supercode preset is CODE — one of the compiled-in preset bundles, not a config home a verb \
     can make or remove. supercode publishes no preset create/delete verb, so the profile noun \
     refuses rather than inventing one";

/// One uniform mutating verb over the profile noun.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ProfileVerb {
    /// Make a new named config home.
    Create,
    /// Remove a named config home.
    Delete,
}

impl ProfileVerb {
    /// Uniform spelling used in the RPC method and in outcomes.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Create => "create",
            Self::Delete => "delete",
        }
    }
}

/// One mutating request, in the uniform Domain 11 vocabulary.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProfileMutation {
    /// Harness that owns the profile.
    pub harness: String,
    /// Profile / agent name to create or delete.
    pub name: String,
    /// Existing profile the new one is cloned from, where the harness has a
    /// verb for it (Hermes `--clone-from`). Refused elsewhere, never dropped.
    #[serde(default, alias = "template")]
    pub from: Option<String>,
    /// Workspace directory for the new agent — required by
    /// `openclaw agents add` in non-interactive mode.
    #[serde(default)]
    pub workspace: Option<String>,
    /// Storage roots, so an isolated home is addressed the same way the read
    /// side addresses it.
    #[serde(default)]
    pub homes: HarnessHomes,
}

/// What one mutation did, with the harness's own row read back afterwards.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProfileMutationOutcome {
    /// Harness that ran the verb.
    pub harness: String,
    /// Uniform verb that was asked for.
    pub verb: String,
    /// The exact harness command that ran, credentials redacted.
    pub ran: String,
    /// Affected profile name, as the harness's own store spells it.
    pub name: String,
    /// The profile as the harness's own store reports it AFTER the verb.
    /// Absent for `delete`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub profile: Option<ProfileRow>,
    /// `true` on a successful `delete`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deleted: Option<bool>,
}

/// Why a profile mutation could not be performed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProfileControlError {
    /// The harness has no verb for what was asked (refused, never faked).
    Unsupported(String),
    /// The request itself is incoherent.
    Invalid(String),
    /// The harness verb ran and failed; the message carries its stderr.
    Failed(String),
}

impl std::fmt::Display for ProfileControlError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Unsupported(message) | Self::Invalid(message) | Self::Failed(message) => {
                formatter.write_str(message)
            }
        }
    }
}

impl std::error::Error for ProfileControlError {}

type Result<T> = std::result::Result<T, ProfileControlError>;

/// Whether `harness` can have its profiles mutated at all.
pub fn supports_profile_control(harness: &str) -> bool {
    CONTROLLED_PROFILE_HARNESSES.contains(&harness)
}

/// The refusal sentence for a harness that cannot be controlled: the reason
/// the HARNESS gives, when it has profiles, and otherwise the same sentence
/// `profiles.list` answers with.
fn unsupported_harness(harness: &str) -> String {
    match harness {
        HarnessId::CODEX => CODEX_REFUSAL.to_string(),
        HarnessId::SUPERCODE => PRESET_REFUSAL.to_string(),
        other => crate::profiles::ProfileError::UnsupportedHarness {
            harness: other.to_string(),
        }
        .to_string(),
    }
}

/// The harness's own executable, refused in the profile noun's words.
fn harness_program(harness: &str) -> Result<String> {
    crate::harness_command::harness_program(harness).map_err(|detail| {
        ProfileControlError::Unsupported(detail.unwrap_or_else(|| unsupported_harness(harness)))
    })
}

/// `HERMES_HOME` for a profile mutation: the ROOT home, never a profile's own
/// home — `HERMES_HOME/profiles/<name>` is what the verb creates or removes,
/// and upstream derives that profiles root from this variable.
fn hermes_home(homes: &HarnessHomes) -> PathBuf {
    // `HarnessHomes::hermes` addresses `state.db`; HERMES_HOME is its parent,
    // the same derivation the read side uses.
    homes
        .hermes
        .parent()
        .map_or_else(|| PathBuf::from("."), Path::to_path_buf)
}

/// Perform one mutation: translate to the harness's own verb, run it, then
/// re-read the row through the ORCH-10 loader.
pub fn mutate(verb: ProfileVerb, mutation: &ProfileMutation) -> Result<ProfileMutationOutcome> {
    if !supports_profile_control(&mutation.harness) {
        return Err(ProfileControlError::Unsupported(unsupported_harness(
            &mutation.harness,
        )));
    }
    let name = mutation.name.trim();
    if name.is_empty() {
        return Err(ProfileControlError::Invalid(format!(
            "`profiles.{}` needs the profile name to act on",
            verb.as_str()
        )));
    }
    if matches!(verb, ProfileVerb::Delete)
        && (mutation.from.is_some() || mutation.workspace.is_some())
    {
        return Err(ProfileControlError::Invalid(
            "`profiles.delete` sets no fields; pass definition fields to `profiles.create`".into(),
        ));
    }
    // ORC-13: the orchestrator's verb is not a CLI subprocess but its own
    // package's operator door, so it branches before the command table.
    if mutation.harness == HarnessId::ORCHESTRATOR {
        return orchestrator_mutate(verb, name, mutation);
    }
    let command = match mutation.harness.as_str() {
        HarnessId::HERMES => hermes_command(verb, name, mutation)?,
        HarnessId::OPENCLAW => openclaw_command(verb, name, mutation)?,
        other => return Err(ProfileControlError::Unsupported(unsupported_harness(other))),
    };
    let ran = command.narrate();
    command.run().map_err(ProfileControlError::Failed)?;
    // The harness's own store is the answer: re-read, never echo the request.
    let read = read_back(&mutation.harness, name, &mutation.homes, &ran)?;
    match verb {
        ProfileVerb::Delete => {
            if read.is_some() {
                return Err(ProfileControlError::Failed(format!(
                    "`{ran}` reported success but `{name}` is still a {} profile",
                    mutation.harness
                )));
            }
            Ok(ProfileMutationOutcome {
                harness: mutation.harness.clone(),
                verb: verb.as_str().to_string(),
                ran,
                name: name.to_string(),
                profile: None,
                deleted: Some(true),
            })
        }
        ProfileVerb::Create => {
            let profile = read.ok_or_else(|| {
                ProfileControlError::Failed(format!(
                    "`{ran}` reported success but `{}` has no profile `{name}` afterwards",
                    mutation.harness
                ))
            })?;
            Ok(ProfileMutationOutcome {
                harness: mutation.harness.clone(),
                verb: verb.as_str().to_string(),
                ran,
                name: profile.name.clone(),
                profile: Some(profile),
                deleted: None,
            })
        }
    }
}

// ---------------------------------------------------------------------------
// The orchestrator — its own package's operator door (ORC-13)
// ---------------------------------------------------------------------------

/// One orchestrator profile mutation: through the package's door, then
/// re-read through the ORCH-10 loader like every other harness's row.
fn orchestrator_mutate(
    verb: ProfileVerb,
    name: &str,
    mutation: &ProfileMutation,
) -> Result<ProfileMutationOutcome> {
    if mutation.from.is_some() {
        return Err(ProfileControlError::Unsupported(
            "an orchestrator profile is a FOLDER the package's `save()` writes from an empty \
             record (`docs/ORCHESTRATOR-IR.md` §6); the operator door has no clone verb, so \
             Volter Harness refuses rather than dropping `from`"
                .into(),
        ));
    }
    if mutation.workspace.is_some() {
        return Err(ProfileControlError::Unsupported(
            "an orchestrator profile IS its own home (`<root>/profiles/<name>`), and where its \
             worker runs is the `worker.cwd` key inside that folder's `config.yaml`, not a \
             creation argument; Volter Harness refuses rather than dropping `workspace`"
                .into(),
        ));
    }
    let root = mutation.homes.orchestrator.clone();
    let op = match verb {
        ProfileVerb::Create => "profiles.create",
        ProfileVerb::Delete => "profiles.delete",
    };
    let args = serde_json::json!({ "name": name });
    // Profile verbs act on the HOME, not inside a profile; `default` is the
    // root folder and always exists, so it is the door's context.
    let answer =
        crate::orchestrator_door::call(&root, op, &args, "default").map_err(
            |error| match error {
                crate::orchestrator_door::DoorError::Refused(message) => {
                    ProfileControlError::Failed(message)
                }
                crate::orchestrator_door::DoorError::Failed(message) => {
                    ProfileControlError::Failed(message)
                }
            },
        )?;
    let ran = format!("{} [{}]", answer.ran, answer.door.as_str());
    // The FOLDER is the answer, re-read through the same loader
    // `profiles list` uses — never the door's echo of what it wrote.
    let read = read_back(&mutation.harness, name, &mutation.homes, &ran)?;
    match verb {
        ProfileVerb::Delete => {
            if read.is_some() {
                return Err(ProfileControlError::Failed(format!(
                    "`{ran}` reported success but `{name}` is still an orchestrator profile"
                )));
            }
            Ok(ProfileMutationOutcome {
                harness: mutation.harness.clone(),
                verb: verb.as_str().to_string(),
                ran,
                name: name.to_string(),
                profile: None,
                deleted: Some(true),
            })
        }
        ProfileVerb::Create => {
            let profile = read.ok_or_else(|| {
                ProfileControlError::Failed(format!(
                    "`{ran}` reported success but the orchestrator has no profile `{name}` \
                     afterwards"
                ))
            })?;
            Ok(ProfileMutationOutcome {
                harness: mutation.harness.clone(),
                verb: verb.as_str().to_string(),
                ran,
                name: profile.name.clone(),
                profile: Some(profile),
                deleted: None,
            })
        }
    }
}

/// The profile the harness's own store holds under `name` after the verb.
///
/// Both harnesses normalize the id they are handed (Hermes lowercases in
/// `normalize_profile_name`, OpenClaw in `normalizeAgentId`), so an exact miss
/// falls back to a case-insensitive match and the ROW's own spelling is what
/// the outcome reports.
fn read_back(
    harness: &str,
    name: &str,
    homes: &HarnessHomes,
    ran: &str,
) -> Result<Option<ProfileRow>> {
    let rows = crate::profiles::list_profiles(homes, Some(harness)).map_err(|error| {
        ProfileControlError::Failed(format!(
            "`{ran}` succeeded but the profile store could not be re-read: {error}"
        ))
    })?;
    Ok(rows
        .iter()
        .find(|row| row.name == name)
        .or_else(|| rows.iter().find(|row| row.name.eq_ignore_ascii_case(name)))
        .cloned())
}

// ---------------------------------------------------------------------------
// Hermes — `hermes profile create | delete` over HERMES_HOME
// ---------------------------------------------------------------------------

fn hermes_command(
    verb: ProfileVerb,
    name: &str,
    mutation: &ProfileMutation,
) -> Result<HarnessCommand> {
    if mutation.workspace.is_some() {
        return Err(ProfileControlError::Unsupported(
            "a hermes profile IS its own home (`HERMES_HOME/profiles/<name>`); `hermes profile \
             create` has no workspace flag, so Volter Harness refuses rather than dropping the field"
                .into(),
        ));
    }
    let mut command = HarnessCommand::new(harness_program(HarnessId::HERMES)?);
    command.env(
        "HERMES_HOME",
        hermes_home(&mutation.homes).to_string_lossy(),
    );
    command.arg("profile");
    match verb {
        ProfileVerb::Create => {
            command.arg("create");
            if let Some(from) = mutation
                .from
                .as_deref()
                .map(str::trim)
                .filter(|from| !from.is_empty())
            {
                command.args(["--clone-from", from]);
            }
            // The wrapper script lands in `~/.local/bin`, OUTSIDE the home the
            // caller addressed; a programmatic create never installs an
            // executable on the caller's PATH.
            command.arg("--no-alias");
            command.arg(name);
        }
        ProfileVerb::Delete => {
            // `hermes profile delete` prompts for the profile name typed back
            // unless `--yes` is passed; a prompt on a null stdin would hang.
            command.args(["delete", "--yes", name]);
        }
    }
    Ok(command)
}

// ---------------------------------------------------------------------------
// OpenClaw — `openclaw agents add | delete` over its own state dir
// ---------------------------------------------------------------------------

fn openclaw_command(
    verb: ProfileVerb,
    name: &str,
    mutation: &ProfileMutation,
) -> Result<HarnessCommand> {
    if mutation.from.is_some() {
        return Err(ProfileControlError::Unsupported(
            "`openclaw agents add` takes a workspace, a model and bindings; it has no clone / \
             template source, so Volter Harness refuses rather than dropping `from`"
                .into(),
        ));
    }
    let mut command = HarnessCommand::new(harness_program(HarnessId::OPENCLAW)?);
    // Point the spawned CLI at the SAME state the read side addresses, using
    // openclaw's own environment contract (`OPENCLAW_STATE_DIR` names the
    // state dir; `OPENCLAW_CONFIG_PATH` names the config file inside it).
    command.env(
        "OPENCLAW_STATE_DIR",
        mutation.homes.openclaw.to_string_lossy(),
    );
    command.env(
        "OPENCLAW_CONFIG_PATH",
        mutation
            .homes
            .openclaw
            .join("openclaw.json")
            .to_string_lossy(),
    );
    command.arg("agents");
    match verb {
        ProfileVerb::Create => {
            let workspace = mutation
                .workspace
                .as_deref()
                .map(str::trim)
                .filter(|workspace| !workspace.is_empty())
                .ok_or_else(|| {
                    ProfileControlError::Invalid(
                        "`openclaw agents add` requires the new agent's workspace directory in \
                         non-interactive mode (its own message: \"Non-interactive agent creation \
                         requires --workspace\"), so `profiles.create --harness openclaw` needs \
                         `workspace`"
                            .into(),
                    )
                })?;
            command.args(["add", name, "--workspace", workspace]);
            command.args(["--non-interactive", "--json"]);
        }
        ProfileVerb::Delete => {
            // Without `--force` the verb prompts on a TTY and refuses off one
            // ("Non-interactive session. Re-run with --force.").
            command.args(["delete", name, "--force", "--json"]);
        }
    }
    Ok(command)
}