@maudecode/talaria-web 1.17.2 → 1.19.0

package/sidecar/talaria_sidecar/methods/checkpoints.py

@@ -0,0 +1,89 @@
+"""``checkpoints.*``: a workspace's filesystem checkpoints through the Agent's own ``CheckpointManager`` (TAL-913).
+
+The Agent keeps every project's checkpoints as refs in one shared git store under the profile home; listing, diffing and
+restoring go through its manager so the store layout, the nested-repository refusal and the pre-rollback snapshot stay
+the Agent's.
+"""
+
+from __future__ import annotations
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+
+def checkpoint_kwargs() -> dict:
+    """The profile's ``checkpoints`` config as ``AIAgent`` kwargs, resolved as the Agent's gateway does
+    (``gateway/run.py::_checkpoint_agent_kwargs``): the legacy ``checkpoints: true`` form, else the section over
+    ``DEFAULT_CONFIG``. Only a real ``true`` turns them on, so a quoted ``"false"`` stays off."""
+    from hermes_cli.config import DEFAULT_CONFIG, load_config
+
+    section = (load_config() or {}).get("checkpoints", {})
+    if isinstance(section, bool):
+        section = {"enabled": section}
+    elif not isinstance(section, dict):
+        section = {}
+    defaults = DEFAULT_CONFIG["checkpoints"]
+    return {
+        "checkpoints_enabled": section.get("enabled", defaults["enabled"]) is True,
+        "checkpoint_max_snapshots": section.get("max_snapshots", defaults["max_snapshots"]),
+        "checkpoint_max_total_size_mb": section.get("max_total_size_mb", defaults["max_total_size_mb"]),
+        "checkpoint_max_file_size_mb": section.get("max_file_size_mb", defaults["max_file_size_mb"]),
+    }
+
+
+def _manager():
+    from tools.checkpoint_manager import CheckpointManager
+
+    kwargs = checkpoint_kwargs()
+    return CheckpointManager(enabled=kwargs["checkpoints_enabled"], max_snapshots=kwargs["checkpoint_max_snapshots"],
+                             max_total_size_mb=kwargs["checkpoint_max_total_size_mb"], max_file_size_mb=kwargs["checkpoint_max_file_size_mb"])
+
+
+def _param(params: dict, name: str) -> str:
+    value = params.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidParams(f"{name} is required")
+    return value
+
+
+def _agent_result(result: dict) -> dict:
+    """The Agent answers a refusal (unknown checkpoint, uncaptured nested repository, failed checkout) as ``success: False``."""
+    if not result.get("success"):
+        raise RpcError(str(result.get("error") or "checkpoint operation failed"), condition="checkpoint_failed")
+    return result
+
+
+def _owned(manager, workspace: str, checkpoint: str) -> str:
+    """The full hash of ``checkpoint`` among ``workspace``'s own checkpoints. The store is shared by every project and the
+    Agent's diff and restore accept any commit in it, so another workspace's hash would check that tree out here."""
+    matches = [c["hash"] for c in manager.list_checkpoints(workspace) if c.get("hash") and str(c["hash"]).startswith(checkpoint.lower())]
+    if len(matches) != 1:
+        raise RpcError(f"Checkpoint '{checkpoint}' is not a checkpoint of this workspace", condition="checkpoint_failed")
+    return matches[0]
+
+
+def register(registry) -> None:
+    @registry.method("checkpoints.list")
+    def list_(ctx: CallContext, params: dict) -> dict:
+        workspace = _param(params, "workspace")
+        with scoped_home(profile_home_param(params)):
+            from tools.checkpoint_manager import _store_path
+
+            return {"checkpoints": _manager().list_checkpoints(workspace), "store": str(_store_path())}
+
+    @registry.method("checkpoints.diff")
+    def diff(ctx: CallContext, params: dict) -> dict:
+        workspace, checkpoint = _param(params, "workspace"), _param(params, "checkpoint")
+        with scoped_home(profile_home_param(params)):
+            manager = _manager()
+            result = _agent_result(manager.diff(workspace, _owned(manager, workspace, checkpoint)))
+        return {"stat": str(result.get("stat") or ""), "diff": str(result.get("diff") or "")}
+
+    @registry.method("checkpoints.restore")
+    def restore(ctx: CallContext, params: dict) -> dict:
+        workspace, checkpoint = _param(params, "workspace"), _param(params, "checkpoint")
+        with scoped_home(profile_home_param(params)):
+            manager = _manager()
+            result = _agent_result(manager.restore(workspace, _owned(manager, workspace, checkpoint)))
+        return {"restored_to": str(result.get("restored_to") or ""), "reason": str(result.get("reason") or "")}

package/sidecar/talaria_sidecar/methods/commands.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
+import contextlib
+import importlib.util
 import logging
+import os
+import pathlib
 import threading
 from typing import Any
 
@@ -40,6 +44,103 @@ def parse_slash_command(command: str) -> tuple[str, str]:
     return _ALIASES.get(base, base), parts[1] if len(parts) > 1 else ""
 
 
+def _expand_plan(args: str, **_turn) -> str:
+    from agent.plan_prompt import build_plan_prompt
+
+    return build_plan_prompt(args)
+
+
+def _expand_learn(args: str, **_turn) -> str:
+    from agent.learn_prompt import build_learn_prompt
+
+    return build_learn_prompt(args)
+
+
+def _expand_init(args: str, *, workspace: str, **_turn) -> str:
+    from hermes_cli.init_command import build_init_prompt_for_cwd
+
+    # The Agent falls back to the process cwd for a missing directory; the sidecar's is never the user's project.
+    if not workspace or not os.path.isdir(workspace):
+        raise InvalidParams("workspace is not a directory")
+    return build_init_prompt_for_cwd(cwd=workspace, extra=args)
+
+
+def _expand_initiate_setup(_args: str, *, enabled_toolsets, **_turn) -> str:
+    from agent.initiate_setup_prompt import build_initiate_setup_prompt
+    from hermes_cli.setup_profile import primary_profile
+    from hermes_constants import get_hermes_home
+    from model_tools import get_tool_definitions
+
+    from .chat import _turn_toolsets
+    from .toolsets import disabled_toolsets
+
+    # The gateway's ``_hm_cmd_initiate_setup``: the tools this turn's agent gets, by name. MCP servers connect first, as
+    # chat start connects them before its agent snapshots tools; a failure leaves them out, as it does for the turn.
+    try:
+        discover_profile_mcp_tools()
+    except Exception:  # noqa: BLE001
+        log.warning("MCP discovery failed", exc_info=True)
+    tools = get_tool_definitions(enabled_toolsets=_turn_toolsets(enabled_toolsets), disabled_toolsets=disabled_toolsets(),
+                                 quiet_mode=True, skip_tool_search_assembly=True)
+    return build_initiate_setup_prompt("webui", [tool["function"]["name"] for tool in tools], primary_profile(get_hermes_home()))
+
+
+# The Agent built-ins every surface answers by rewriting the turn to a builder's prompt (the gateway's
+# ``_hm_rewrite_turn_to_prompt``), with the Agent module each expander needs. ``None``: no expander yet, so no client
+# offers it (``/blueprint`` seeds a turn only after its own slot parsing and job wiring).
+_PROMPT_BUILTINS: dict[str, tuple[Any, str] | None] = {
+    "plan": (_expand_plan, "agent.plan_prompt"),
+    "learn": (_expand_learn, "agent.learn_prompt"),
+    "init": (_expand_init, "hermes_cli.init_command"),
+    "initiate-setup": (_expand_initiate_setup, "agent.initiate_setup_prompt"),
+    "blueprint": None,
+}
+
+
+def _prompt_expander(name: str):
+    """The expander for a prompt built-in this Agent ships the builder for; None when it has none."""
+    entry = _PROMPT_BUILTINS.get(name)
+    if entry is None:
+        return None
+    try:
+        found = importlib.util.find_spec(entry[1]) is not None
+    except (ImportError, ValueError):
+        found = False
+    return entry[0] if found else None
+
+
+def _prompt_mode(name: str) -> str | None:
+    if name not in _PROMPT_BUILTINS:
+        return None
+    return "expand" if _prompt_expander(name) else "unsupported"
+
+
+def expand_prompt(command: str, workspace: str, enabled_toolsets) -> dict[str, Any]:
+    """``/<prompt built-in> [args]`` as the turn text the Agent's own builder writes. ``name`` is the built-in's (None
+    when the command is not one) and ``message`` None when this Agent has no builder for it."""
+    try:
+        name, args = parse_slash_command(command)
+        from hermes_cli.commands import resolve_command
+    except (InvalidParams, ImportError):
+        return {"name": None, "message": None}
+    cmd = resolve_command(name)
+    if cmd is None or cmd.name not in _PROMPT_BUILTINS:
+        return {"name": None, "message": None}
+    expander = _prompt_expander(cmd.name)
+    if expander is None:
+        return {"name": cmd.name, "message": None}
+    try:
+        message = str(expander(args, workspace=workspace, enabled_toolsets=enabled_toolsets) or "").strip()
+    except InvalidParams:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Failed to expand /%s", cmd.name, exc_info=True)
+        raise RpcError(f"Couldn't start /{cmd.name}", condition="prompt_expand_failed") from exc
+    if not message:
+        raise RpcError(f"Couldn't start /{cmd.name}", condition="prompt_expand_failed")
+    return {"name": cmd.name, "message": message}
+
+
 def list_commands() -> list[dict[str, Any]]:
     try:
         from hermes_cli.commands import COMMAND_REGISTRY
@@ -53,13 +154,13 @@ def list_commands() -> list[dict[str, Any]]:
         out.append({
             "name": cmd.name, "description": cmd.description, "category": cmd.category, "aliases": list(cmd.aliases),
             "args_hint": cmd.args_hint, "subcommands": list(cmd.subcommands), "cli_only": bool(cmd.cli_only), "gateway_only": bool(cmd.gateway_only),
-            "exec": cmd.name in _ALLOWED,
+            "exec": cmd.name in _ALLOWED, "prompt": _prompt_mode(cmd.name),
         })
     listed = {c["name"] for c in out}
     for name, (description, category, args_hint) in _RUNTIME_COMMANDS.items():
         if name not in listed:
             out.append({"name": name, "description": description, "category": category, "aliases": [a for a, n in _ALIASES.items() if n == name],
-                        "args_hint": args_hint, "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True})
+                        "args_hint": args_hint, "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True, "prompt": None})
     try:
         from hermes_cli.plugins import get_plugin_commands
 
@@ -68,7 +169,7 @@ def list_commands() -> list[dict[str, Any]]:
             if name in existing or name in _NEVER_EXPOSE:
                 continue
             out.append({"name": name, "description": str(info.get("description", "Plugin command")), "category": "Plugin", "aliases": [],
-                        "args_hint": str(info.get("args_hint", "")), "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True})
+                        "args_hint": str(info.get("args_hint", "")), "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True, "prompt": None})
     except Exception:  # noqa: BLE001 - plugin registry is optional
         log.debug("plugin command listing failed", exc_info=True)
     return out
@@ -95,15 +196,27 @@ def retire_unscoped_launch_mcp_servers() -> set[str]:
     return names
 
 
+def discover_profile_mcp_tools() -> list[str]:
+    """Connect this profile's configured servers, retiring pre-multiplex launch connections first."""
+    from tools.mcp_tool_discovery import discover_mcp_tools
+
+    retire_unscoped_launch_mcp_servers()
+    return discover_mcp_tools()
+
+
 def _reload_mcp() -> str:
     with _RELOAD_MCP_LOCK:
         try:
             from agent.secret_scope import is_multiplex_active
+            from hermes_constants import get_hermes_home
             from tools.mcp_tool import _lock, _mcp_tool_server_names, _server_visible_in_scope, _servers
+            from tools.mcp_tool_agent import reprobe_tool_availability
             from tools.mcp_tool_discovery import discover_mcp_tools
             from tools.mcp_tool_lifecycle import shutdown_mcp_servers
             from tools.mcp_tool_scope import _key_name
             from tools.registry import registry
+
+            from .chat import refresh_profile_agents_mcp_tools
         except Exception as exc:  # noqa: BLE001
             raise RpcError("MCP runtime unavailable", condition="mcp_unavailable") from exc
         # Like the gateway's ``_execute_mcp_reload``: under multiplexing only this profile's connections go down and
@@ -117,7 +230,11 @@ def _reload_mcp() -> str:
         try:
             old = server_names() | retire_unscoped_launch_mcp_servers()
             shutdown_mcp_servers(scope=scope)
+            # As the gateway does: drop the cached tool availability verdicts, then hand the profile's open chats the
+            # rediscovered tools.
+            reprobe_tool_availability()
             tools = discover_mcp_tools() or []
+            refresh_profile_agents_mcp_tools(get_hermes_home())
             connected = server_names()
             if scope is not None:
                 with _lock:
@@ -244,6 +361,77 @@ def execute_plugin_command(command: str) -> str | None:
         return f"Plugin command error: {type(exc).__name__}"
 
 
+def _profile_bundles(skill_bundles) -> dict[str, dict[str, Any]]:
+    """The scoped profile's bundles keyed ``/slug``, read from disk the way ``scan_bundles`` reads them.
+
+    ``scan_bundles``/``get_skill_bundles`` publish one profile's bundles in a process-wide cache keyed only by mtime,
+    which cron jobs in other profiles read concurrently, so the sidecar never fills it."""
+    out: dict[str, dict[str, Any]] = {}
+    for path in skill_bundles._iter_bundle_files():
+        info = skill_bundles._load_bundle_file(path)
+        if info:
+            out.setdefault(f"/{info['slug']}", info)
+    return out
+
+
+def list_command_bundles() -> list[dict[str, Any]]:
+    """The profile's skill bundles as slash-command rows; [] when the bundle runtime is missing or fails."""
+    try:
+        import agent.skill_bundles as skill_bundles
+    except ImportError:
+        return []
+    try:
+        bundles = sorted(_profile_bundles(skill_bundles).values(), key=lambda b: b["slug"])
+    except Exception:  # noqa: BLE001
+        log.warning("Failed to list skill bundles", exc_info=True)
+        return []
+    return [{"name": str(b["slug"]).strip().lower(), "description": str(b.get("description") or "").strip() or "Skill bundle",
+             "skill_count": len(b.get("skills") or []), "source": "bundle"} for b in bundles if str(b.get("slug") or "").strip()]
+
+
+def _bundle_invocation(info: dict[str, Any], instruction: str) -> tuple[str, list[str], list[str]] | None:
+    """``build_bundle_invocation_message`` for a bundle read by ``_profile_bundles`` (that one looks it up in the shared cache),
+    skipping the skills disabled for Web chat (``skills.platform_disabled.webui``)."""
+    from agent.skill_commands import _disabled_skill_names, _load_skill_blocks, _load_skill_payload, _scaffold_header
+
+    name = info["name"]
+    loaded, missing, disabled, blocks = _load_skill_blocks(
+        [(skill or "").strip() for skill in info["skills"]], _load_skill_payload, lambda _skill: f'[Loaded as part of the "{name}" skill bundle.]',
+        None, disabled_names=_disabled_skill_names("webui"))
+    if not blocks:
+        return None
+    header = _scaffold_header(f'"{name}" skill bundle', loaded, lead_lines=[f"Bundle: {name}"], missing=missing, disabled=disabled,
+                              extra_instruction=info.get("instruction") or "", user_instruction=instruction)
+    return "\n\n".join([header, *blocks]), loaded, missing
+
+
+def resolve_bundle_command(command: str) -> dict[str, Any]:
+    """Expand ``/<bundle> [instruction]`` into the user message that loads the bundle's skills."""
+    name, instruction = parse_slash_command(command)
+    try:
+        import agent.skill_bundles as skill_bundles
+        from agent.skill_commands import resolve_slash_key
+    except ImportError as exc:
+        raise RpcError("Skill bundle runtime unavailable", condition="bundle_unavailable") from exc
+    try:
+        bundles = _profile_bundles(skill_bundles)
+        key = resolve_slash_key(name, bundles)
+        result = _bundle_invocation(bundles[key], instruction) if key else None
+    except ValueError as exc:
+        raise InvalidParams(str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Failed to resolve skill bundle command", exc_info=True)
+        raise RpcError("Skill bundle command unavailable", condition="bundle_unavailable") from exc
+    if key is None:
+        raise RpcError("Bundle command not found", condition="bundle_not_found")
+    message, loaded, missing = result or ("", [], [])
+    message = str(message or "").strip()
+    if not message:
+        raise RpcError("Bundle command returned no invocation text", condition="bundle_unavailable")
+    return {"name": key.lstrip("/"), "source": "bundle", "message": message, "loaded_skills": [str(s) for s in loaded or []],
+            "missing_skills": [str(s) for s in missing or []]}
+
+
 def resolve_moa_config(preset: str | None) -> dict:
     try:
         from hermes_cli.moa_config import moa_usage, normalize_moa_config
@@ -333,6 +521,74 @@ def plugin_visibility(selected_providers: dict) -> dict:
     return {"plugins": rows, "supported_hooks": list(PLUGIN_VISIBILITY_HOOKS)}
 
 
+def isolation_survey(base_home: pathlib.Path) -> list[dict]:
+    """Each profile's ``plugins.isolation`` and installed third-party plugin count, read from disk without loading a plugin."""
+    from hermes_cli.plugin_isolation import isolation_mode
+    from hermes_cli.plugins_cmd import _scan_level
+
+    from .profiles import _yaml_load, named_profile_homes
+
+    rows = []
+    for name, home in [("default", base_home), *named_profile_homes(base_home)]:
+        seen: dict = {}
+        _scan_level(home / "plugins", "user", set(), "", 0, seen)
+        rows.append({"name": name, "isolation": isolation_mode(_yaml_load(home / "config.yaml") or {}), "third_party_plugins": len(seen)})
+    return rows
+
+
+def _plugin_settings_modules():
+    """The Agent's manifest ``config_schema`` reader/writer (v0.21.6+) and its plugin resolver; ``None`` on older Agents."""
+    try:
+        import hermes_cli.plugins_cmd as plugins_cmd
+        import hermes_cli.plugins_settings as plugins_settings
+    except ImportError:
+        return None
+    return plugins_cmd, plugins_settings
+
+
+def plugin_settings() -> dict:
+    """Every discovered plugin whose manifest declares settings, with its fields (secrets as ``env`` + ``has_value`` only)."""
+    modules = _plugin_settings_modules()
+    if modules is None:
+        return {"supported": False, "plugins": []}
+    plugins_cmd, plugins_settings = modules
+    rows = []
+    for _name, _version, _desc, _source, plugin_dir, key in plugins_cmd._discover_all_plugins():
+        fields = plugins_settings.plugin_settings_fields(key, pathlib.Path(str(plugin_dir)) if plugin_dir else None)
+        if fields:
+            rows.append({"key": key, "fields": fields})
+    return {"supported": True, "plugins": rows}
+
+
+def save_plugin_settings(key: str, values: Any, secret_envs: Any = None) -> dict:
+    """Write manifest-declared, non-secret settings through the Agent's locked writer; returns the refreshed fields.
+
+    ``secret_envs`` (secret key -> ``.env`` name the caller wrote) must still match the manifest before anything is written.
+    """
+    if not key or not isinstance(values, dict) or not isinstance(secret_envs or {}, dict):
+        raise InvalidParams("plugins.settings_save requires a 'key' and a 'values' mapping")
+    modules = _plugin_settings_modules()
+    if modules is None:
+        raise RpcError("This Hermes Agent cannot edit plugin settings", condition="plugin_settings_unsupported")
+    plugins_cmd, plugins_settings = modules
+    found = plugins_cmd._find_plugin_entry(key)
+    if found is None:
+        raise RpcError(f"plugin {key!r} not found", condition="plugin_not_found")
+    plugin_dir = pathlib.Path(str(found[4])) if found[4] else None
+    current = {field["key"]: field for field in plugins_settings.plugin_settings_fields(found[5], plugin_dir)}
+    for secret, env in (secret_envs or {}).items():
+        field = current.get(str(secret))
+        if field is None or field.get("type") != "secret" or field.get("env") != env:
+            raise RpcError(f"{secret!r} is no longer stored in {env}", condition="plugin_settings_changed")
+    try:
+        written = plugins_settings.save_plugin_settings(found[5], plugin_dir, values)
+    except PermissionError as exc:
+        raise RpcError(str(exc), condition="plugin_settings_managed") from exc
+    except ValueError as exc:
+        raise InvalidParams(str(exc)) from exc
+    return {"key": found[5], "written": written, "fields": plugins_settings.plugin_settings_fields(found[5], plugin_dir)}
+
+
 def register(registry) -> None:
     @registry.method("commands.registry")
     def registry_(ctx: CallContext, params: dict) -> dict:
@@ -346,12 +602,32 @@ def register(registry) -> None:
             output = execute_agent_command(command)
             source = "agent"
             if output is None:
-                output = execute_plugin_command(command)
+                from .chat import _turn_identity
+
+                # TAL-904: a chat's plugin command runs under that chat's session and workspace, as its turns do.
+                session_id = str(params.get("session_id") or "").strip()
+                with _turn_identity(session_id, str(params.get("workspace") or "")) if session_id else contextlib.nullcontext():
+                    output = execute_plugin_command(command)
                 source = "plugin"
         if output is None:
             raise RpcError(f"unknown command {parse_slash_command(command)[0]!r}", condition="command_not_found")
         return {"output": output, "source": source}
 
+    @registry.method("commands.expand_prompt")
+    def expand_prompt_(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return expand_prompt(str(params.get("command") or ""), str(params.get("workspace") or ""), params.get("enabled_toolsets"))
+
+    @registry.method("commands.bundles")
+    def bundles(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return {"bundles": list_command_bundles()}
+
+    @registry.method("commands.bundle_resolve")
+    def bundle_resolve(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return resolve_bundle_command(str(params.get("command") or ""))
+
     @registry.method("commands.moa_preset")
     def moa(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
@@ -366,3 +642,17 @@ def register(registry) -> None:
     def list_(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
             return plugin_visibility(params.get("selected_providers") if isinstance(params.get("selected_providers"), dict) else {})
+
+    @registry.method("plugins.isolation")
+    def isolation(ctx: CallContext, params: dict) -> dict:
+        return {"profiles": isolation_survey(profile_home_param(params, "base_home"))}
+
+    @registry.method("plugins.settings")
+    def settings(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return plugin_settings()
+
+    @registry.method("plugins.settings_save")
+    def settings_save(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return save_plugin_settings(str(params.get("key") or "").strip(), params.get("values"), params.get("secret_envs"))

package/sidecar/talaria_sidecar/methods/config.py

@@ -1,16 +1,20 @@
-"""``config.*`` and ``models.reasoning_efforts``: a profile's ``config.yaml`` and the
-Agent's per-model reasoning capability.
+"""``config.*``, ``models.reasoning_efforts`` and ``personalities.list``: a profile's ``config.yaml`` and ``.env``,
+the Agent's per-model reasoning capability, and the personalities the Agent offers for a config.
 
 The TypeScript server owns every config.yaml *policy* (which keys mean what);
 the sidecar only parses and serialises YAML with the Agent's own parser so the
 Node side needs no YAML dependency. Writes are atomic and keep the file's mode.
+``.env`` edits use the Agent's own line helpers under the ``<.env>.lock`` the
+gateway, CLI and plugins also take, so concurrent writers never drop a key.
 """
 
 from __future__ import annotations
 
+import contextlib
 import importlib
 import logging
 import os
+import re
 import tempfile
 from pathlib import Path
 
@@ -74,7 +78,11 @@ def write_config(path: Path, config: dict) -> dict:
         raise InvalidParams("config must be an object")
     target = _write_target(path)
     target.parent.mkdir(parents=True, exist_ok=True)
-    text = yaml_parser().safe_dump(config, sort_keys=False, allow_unicode=True)
+    try:
+        replace = getattr(importlib.import_module("hermes_cli.config"), "atomic_config_replace", None)
+    except Exception:  # noqa: BLE001
+        # Operator config must remain writable even when Agent imports are broken.
+        replace = None
     mode = None
     try:
         mode = target.stat().st_mode & 0o777
@@ -83,9 +91,20 @@ def write_config(path: Path, config: dict) -> dict:
     fd, tmp = tempfile.mkstemp(dir=str(target.parent), prefix=".config_", suffix=".tmp")
     try:
         with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            handle.write(text)
+            if replace is not None:
+                # Stage the original document so the Agent retains comments; check the real link before committing.
+                try:
+                    handle.write(target.read_text(encoding="utf-8"))
+                except FileNotFoundError:
+                    pass
+            else:
+                parser = yaml_parser()
+                handle.write(parser.safe_dump(config, sort_keys=False, allow_unicode=True,
+                                              width=getattr(parser, "ROUNDTRIP_YAML_WIDTH", 2**31 - 1)))
             handle.flush()
             os.fsync(handle.fileno())
+        if replace is not None:
+            replace(Path(tmp), config)
         if mode is not None:
             os.chmod(tmp, mode)
         # A link retargeted while the temp file was being written would otherwise send the write to the wrong file.
@@ -101,6 +120,88 @@ def write_config(path: Path, config: dict) -> dict:
     return {"ok": True, "path": str(path)}
 
 
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _env_refusal(agent_config, key: str, action: str) -> str | None:
+    """The Agent's ``.env`` write-lock refusal (package-managed install or administrator-managed key)."""
+    refusal = getattr(agent_config, "env_write_refusal", None)
+    if refusal is not None:
+        return refusal(key, action)
+    # Agent 0.21.5 only reports the refusal on stderr.
+    return f"Cannot {action} {key}: this Hermes installation manages it" if agent_config._env_write_blocked(key, action) else None
+
+
+def _env_lock(agent_config, path: Path):
+    """The Agent's ``<.env>.lock`` (Agent 0.21.6+); older Agents have none to share."""
+    lock = getattr(agent_config, "_env_write_lock", None)
+    return lock(path) if lock is not None else contextlib.nullcontext()
+
+
+def env_write(home: Path, updates) -> dict:
+    """Upsert ``updates`` into ``home``'s ``.env`` (``None`` removes a key) with the Agent's own line helpers, under
+    the lock its ``save_env_value`` / ``remove_env_value`` take, in one atomic replace.
+
+    Unlike those two, nothing is published into ``os.environ``: other threads (a gateway spawn snapshotting the
+    environment) must never see another profile's key, and ``runtime.env`` alone owns this process's environment.
+    Values are trimmed and an empty one is skipped; a value the Agent would strip or quote is refused. Every key is
+    checked against the Agent's refusals before the write, and the file ends 0600.
+    """
+    if not isinstance(updates, dict) or not all(isinstance(k, str) and _ENV_NAME.match(k) and (v is None or isinstance(v, str)) for k, v in updates.items()):
+        raise InvalidParams("updates must map variable names to strings or null")
+    changes: dict[str, str | None] = {}
+    for key, value in updates.items():
+        if value is not None:
+            value = value.strip()
+            if not value:
+                continue
+            if "\n" in value or "\r" in value:
+                raise InvalidParams("API key must not contain newline characters.")
+            # The Agent would strip non-ASCII and quote the rest; refused instead, so the running process and the
+            # server's reader see exactly the bytes the file holds.
+            if any(not "!" <= c <= "~" or c in "#\"'" for c in value):
+                raise InvalidParams("API key must not contain spaces, quotes, '#' or non-ASCII characters.")
+        changes[key] = value
+    from hermes_cli import config as agent_config
+
+    with scoped_home(home):
+        for key, value in changes.items():
+            refusal = _env_refusal(agent_config, key, "remove" if value is None else "set")
+            if refusal:
+                raise RpcError(refusal, condition="env_write_refused")
+        try:
+            agent_config.ensure_hermes_home()
+            path = agent_config.get_env_path()
+            with _env_lock(agent_config, path):
+                existed = path.exists()
+                lines = agent_config._read_env_lines(path) if existed else []
+                before = list(lines)
+                for key, value in changes.items():
+                    defines = agent_config._env_line_defines_key
+                    if value is None:
+                        lines = [line for line in lines if not defines(line, key)]
+                        continue
+                    agent_config.validate_env_var_name_for_write(key)
+                    entry = f"{key}={value}\n"
+                    at = next((i for i, line in enumerate(lines) if defines(line, key)), None)
+                    if at is not None:
+                        lines[at] = entry
+                    else:
+                        if lines and not lines[-1].endswith("\n"):
+                            lines[-1] += "\n"
+                        lines.append(entry)
+                if lines != before:
+                    agent_config._write_env_lines(path, lines, preserve_mode=existed)
+        except TimeoutError as exc:
+            raise RpcError(str(exc), condition="env_locked") from exc
+        except ValueError as exc:
+            raise RpcError(str(exc), condition="env_write_refused") from exc
+        agent_config.invalidate_env_cache()
+        if path.exists():
+            os.chmod(path, 0o600)
+    return {"ok": True, "path": str(path)}
+
+
 def reasoning_efforts(model: str, provider: str) -> dict:
     """Levels the Agent would offer for ``model`` on ``provider`` (``hermes_cli.main_provider_setup``)."""
     efforts: list[str] | None = None
@@ -122,6 +223,16 @@ def reasoning_efforts(model: str, provider: str) -> dict:
     return {"efforts": [str(e) for e in (efforts or [])], "supports_reasoning": supports_reasoning}
 
 
+def personalities(config) -> list[dict]:
+    """TAL-901: ``config``'s personalities as the Agent offers them (``hermes_cli.personality``), with its list preview
+    and rendered prompt."""
+    from hermes_cli.personality import available_personalities, describe_personality, render_personality_prompt
+
+    if not isinstance(config, dict):
+        raise InvalidParams("config must be a mapping")
+    return [{"name": name, "description": describe_personality(value), "prompt": render_personality_prompt(value)} for name, value in available_personalities(config).items()]
+
+
 def register(registry) -> None:
     @registry.method("config.get", requires_agent=False)
     def get(ctx: CallContext, params: dict) -> dict:
@@ -131,7 +242,15 @@ def register(registry) -> None:
     def set_(ctx: CallContext, params: dict) -> dict:
         return write_config(config_path_param(params), params.get("config"))
 
+    @registry.method("config.env_write")
+    def env_write_(ctx: CallContext, params: dict) -> dict:
+        return env_write(profile_home_param(params), params.get("updates"))
+
     @registry.method("models.reasoning_efforts")
     def efforts(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
             return reasoning_efforts(str(params.get("model") or ""), str(params.get("provider") or ""))
+
+    @registry.method("personalities.list")
+    def personalities_(ctx: CallContext, params: dict) -> dict:
+        return {"personalities": personalities(params.get("config"))}