agnoctl 0.1.0a1__py3-none-any.whl

agnoctl/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agnoctl")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

agnoctl/clients/__init__.py

@@ -0,0 +1,36 @@
+"""Client adapters: how each coding agent stores MCP server configuration."""
+
+from pathlib import Path
+from typing import Dict, Optional
+
+from agnoctl.clients.base import ClientAdapter, ExistingEntry, WriteResult
+from agnoctl.clients.claude_code import ClaudeCodeAdapter
+from agnoctl.clients.claude_desktop import ClaudeDesktopAdapter
+from agnoctl.clients.codex import CodexAdapter
+from agnoctl.clients.cursor import CursorAdapter
+
+# Accepted spellings for --clients, mapped to canonical adapter keys. "claude" stays
+# bound to Claude Code (the coding agent); the desktop app is claude-desktop.
+CLIENT_ALIASES = {
+    "claude": "claude-code",
+    "claude-code": "claude-code",
+    "claude-desktop": "claude-desktop",
+    "claude-app": "claude-desktop",
+    "codex": "codex",
+    "cursor": "cursor",
+}
+
+
+def build_adapters(
+    home: Optional[Path] = None,
+    cwd: Optional[Path] = None,
+    project: bool = False,
+) -> Dict[str, ClientAdapter]:
+    """All known adapters keyed by canonical client key."""
+    claude_scope = "project" if project else "user"
+    return {
+        "claude-code": ClaudeCodeAdapter(home=home, cwd=cwd, scope=claude_scope),
+        "claude-desktop": ClaudeDesktopAdapter(home=home),
+        "codex": CodexAdapter(home=home),
+        "cursor": CursorAdapter(home=home, cwd=cwd, project=project),
+    }

agnoctl/clients/base.py

@@ -0,0 +1,167 @@
+"""Shared shapes for coding-agent client adapters.
+
+An adapter knows how one coding agent (Claude Code, Codex, Cursor) stores MCP server
+configuration: how to detect the client on this machine, read an existing entry back
+(for idempotent re-runs), and write an entry pointing at an AgentOS MCP endpoint.
+"""
+
+import contextlib
+import json
+import os
+import stat
+import tempfile
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from agnoctl.errors import CLIError
+
+
+@dataclass
+class ExistingEntry:
+    """An MCP server entry found in a client's configuration."""
+
+    url: str
+    token: Optional[str]
+    location: str  # human-readable: file path or config scope it was found in
+
+
+@dataclass
+class WriteResult:
+    """How and where a config write landed."""
+
+    method: str  # "cli" (client's own CLI did the write) | "file" (we edited the config file)
+    location: str
+    note: Optional[str] = None  # caveat worth surfacing to the user (e.g. VCS-shared file)
+
+
+def servers_table(config: object) -> dict:
+    """The mcpServers mapping from a parsed config, tolerating malformed shapes."""
+    if isinstance(config, dict):
+        servers = config.get("mcpServers")
+        if isinstance(servers, dict):
+            return servers
+    return {}
+
+
+def bearer_header(token: str) -> str:
+    return "Bearer " + token
+
+
+def token_from_authorization(value: Optional[str]) -> Optional[str]:
+    """Extract the raw token from an Authorization header value."""
+    if not value:
+        return None
+    if value.lower().startswith("bearer "):
+        return value[len("bearer ") :].strip() or None
+    return value.strip() or None
+
+
+def read_json_lenient(path: Path) -> Optional[Dict[str, Any]]:
+    """For reads: a missing or malformed file simply means no entry found."""
+    if not path.exists():
+        return None
+    try:
+        parsed = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def read_json_strict(path: Path) -> Dict[str, Any]:
+    """For writes: refuse to clobber a file we cannot parse."""
+    if not path.exists():
+        return {}
+    try:
+        parsed = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        raise CLIError(
+            "Refusing to modify " + str(path) + ": the existing file is not valid JSON (" + str(e) + ").",
+            hint="Fix or move the file, then re-run.",
+        )
+    if not isinstance(parsed, dict):
+        raise CLIError("Refusing to modify " + str(path) + ": expected a JSON object at the top level.")
+    return parsed
+
+
+def _plain_file_mode(path: Path) -> int:
+    """The mode a non-secret config write should land with: the target's current mode
+    when we are merging into an existing file, otherwise the process default
+    (``0o666 & ~umask``). This keeps us from silently tightening or loosening an
+    unrelated file that happens to carry no token."""
+    try:
+        return stat.S_IMODE(path.stat().st_mode)
+    except OSError:
+        current = os.umask(0)
+        os.umask(current)
+        return 0o666 & ~current
+
+
+def atomic_write_text(path: Path, text: str, *, secure: bool) -> None:
+    """Write ``text`` to ``path`` atomically, never exposing a secret at wide permissions.
+
+    A crash mid-write must never corrupt the target (these files include Claude Code's
+    whole ``~/.claude.json`` user state), and a token must never touch disk at a
+    world-readable mode -- even transiently, and even if the process dies between the
+    write and a follow-up ``chmod``.
+
+    So: write to a temp file in the *same directory* (so ``os.replace`` is an atomic
+    rename on one filesystem), ``fsync`` it, then replace the target. ``mkstemp`` creates
+    the temp file 0600, so a secret is at 0600 from the instant it hits disk; the replace
+    carries that mode onto the target. Non-secret writes keep the target's existing (or a
+    umask-default) mode.
+    """
+    fd, tmp_name = tempfile.mkstemp(dir=str(path.parent), prefix="." + path.name + ".", suffix=".tmp")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        # mkstemp already created tmp as 0600; set the final mode explicitly so intent is
+        # visible and a non-secret write does not inherit an over-tight 0600 by accident.
+        os.chmod(tmp, 0o600 if secure else _plain_file_mode(path))
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def write_servers_entry(
+    path: Path, server_name: str, entry: Dict[str, Any], *, secure: bool, mkdir: bool = False
+) -> None:
+    """Create or replace one ``mcpServers`` entry in a JSON config file.
+
+    Shared by the file-editing adapters so the safety behavior -- strict parse before
+    write, refusal on a malformed ``mcpServers``, atomic replace, 0600 permissions when
+    the entry carries a token -- cannot drift between clients.
+    """
+    config = read_json_strict(path)
+    servers = config.get("mcpServers")
+    if servers is None:
+        servers = {}
+        config["mcpServers"] = servers
+    elif not isinstance(servers, dict):
+        raise CLIError("Refusing to modify " + str(path) + ": 'mcpServers' is not an object.")
+    servers[server_name] = entry
+    if mkdir:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(path, json.dumps(config, indent=2) + "\n", secure=secure)
+
+
+class ClientAdapter(ABC):
+    key: str
+
+    @abstractmethod
+    def detect(self) -> bool:
+        """Whether this client appears to be installed or configured on this machine."""
+
+    @abstractmethod
+    def read_existing(self, server_name: str) -> Optional[ExistingEntry]:
+        """Return the existing MCP entry for server_name, if any."""
+
+    @abstractmethod
+    def write(self, server_name: str, url: str, token: Optional[str]) -> WriteResult:
+        """Create or replace the MCP entry for server_name. Must be idempotent."""

agnoctl/clients/claude_code.py

@@ -0,0 +1,166 @@
+"""Claude Code adapter.
+
+Preferred write path: the `claude mcp add` CLI (the sanctioned interface; it owns config
+placement). Fallback when the binary is missing: edit the config file for the requested
+scope directly — ~/.claude.json (user scope) or <cwd>/.mcp.json (project scope).
+
+Reads follow Claude Code's same-name resolution precedence: local scope
+(~/.claude.json projects.<cwd>.mcpServers) > project (.mcp.json) > user
+(~/.claude.json mcpServers). Getting this order right matters: the entry this
+adapter reports is the one Claude Code will actually use, which is how connect
+detects stale shadowing entries after a write.
+
+Note: the CLI write path passes the Authorization header via argv, which is transiently
+visible in the local process list. The file fallback avoids this; both paths end with a
+read-back so a write that did not take effect is reported, never assumed.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from agnoctl.clients.base import (
+    ClientAdapter,
+    ExistingEntry,
+    WriteResult,
+    bearer_header,
+    read_json_lenient,
+    servers_table,
+    token_from_authorization,
+    write_servers_entry,
+)
+from agnoctl.errors import CLIError
+
+SUBPROCESS_TIMEOUT = 60.0
+
+
+def _redact_token(text: str, token: Optional[str]) -> str:
+    """Strip the bearer token (raw and as an Authorization value) out of a string before
+    it reaches a user-facing error or JSON output."""
+    if not token:
+        return text
+    return text.replace(bearer_header(token), "Bearer ***").replace(token, "***")
+
+
+def _entry_from_servers(servers: Dict[str, Any], server_name: str, location: str) -> Optional[ExistingEntry]:
+    entry = servers.get(server_name)
+    if not isinstance(entry, dict):
+        return None
+    url = entry.get("url")
+    if not isinstance(url, str) or not url:
+        return None
+    headers = entry.get("headers")
+    if not isinstance(headers, dict):
+        headers = {}
+    return ExistingEntry(url=url, token=token_from_authorization(headers.get("Authorization")), location=location)
+
+
+class ClaudeCodeAdapter(ClientAdapter):
+    key = "claude-code"
+
+    def __init__(
+        self,
+        home: Optional[Path] = None,
+        cwd: Optional[Path] = None,
+        scope: str = "user",
+        which: Callable[[str], Optional[str]] = shutil.which,
+        runner: Callable[..., "subprocess.CompletedProcess[str]"] = subprocess.run,
+    ):
+        self.home = home or Path.home()
+        self.cwd = cwd or Path.cwd()
+        self.scope = scope
+        self._which = which
+        self._runner = runner
+
+    @property
+    def _user_config_path(self) -> Path:
+        return self.home / ".claude.json"
+
+    @property
+    def _project_config_path(self) -> Path:
+        return self.cwd / ".mcp.json"
+
+    def detect(self) -> bool:
+        return self._which("claude") is not None or self._user_config_path.exists()
+
+    def read_existing(self, server_name: str) -> Optional[ExistingEntry]:
+        """Return the entry Claude Code would resolve: local > project > user scope."""
+        user_config = read_json_lenient(self._user_config_path)
+
+        if user_config:
+            projects = user_config.get("projects")
+            if isinstance(projects, dict):
+                project = projects.get(str(self.cwd))
+                if isinstance(project, dict):
+                    entry = _entry_from_servers(
+                        servers_table(project), server_name, str(self._user_config_path) + " (local scope)"
+                    )
+                    if entry:
+                        return entry
+
+        project_config = read_json_lenient(self._project_config_path)
+        if project_config:
+            entry = _entry_from_servers(servers_table(project_config), server_name, str(self._project_config_path))
+            if entry:
+                return entry
+
+        if user_config:
+            entry = _entry_from_servers(
+                servers_table(user_config), server_name, str(self._user_config_path) + " (user scope)"
+            )
+            if entry:
+                return entry
+        return None
+
+    def write(self, server_name: str, url: str, token: Optional[str]) -> WriteResult:
+        if self._which("claude") is not None:
+            self._write_via_cli(server_name, url, token)
+            return WriteResult(method="cli", location="claude mcp add (scope: " + self.scope + ")")
+        if self.scope == "project":
+            return self._write_config_file(self._project_config_path, server_name, url, token)
+        return self._write_config_file(self._user_config_path, server_name, url, token)
+
+    # -- CLI path ---------------------------------------------------------------
+
+    def _run_claude(self, args: List[str]) -> "subprocess.CompletedProcess[str]":
+        try:
+            return self._runner(
+                args,
+                capture_output=True,
+                text=True,
+                timeout=SUBPROCESS_TIMEOUT,
+                stdin=subprocess.DEVNULL,
+            )
+        except subprocess.TimeoutExpired:
+            raise CLIError("The claude CLI did not respond within " + str(int(SUBPROCESS_TIMEOUT)) + "s: " + args[2])
+
+    def _write_via_cli(self, server_name: str, url: str, token: Optional[str]) -> None:
+        # Variadic flags (--header) must come after the name and URL, or Claude Code's
+        # parser consumes the positional arguments.
+        add_args: List[str] = ["claude", "mcp", "add", "--transport", "http", "--scope", self.scope, server_name, url]
+        if token:
+            add_args += ["--header", "Authorization: " + bearer_header(token)]
+
+        result = self._run_claude(add_args)
+        if result.returncode != 0 and "already exists" in (result.stderr or "").lower():
+            remove = self._run_claude(["claude", "mcp", "remove", "--scope", self.scope, server_name])
+            if remove.returncode == 0:
+                result = self._run_claude(add_args)
+        if result.returncode != 0:
+            detail = (result.stderr or result.stdout or "").strip()
+            # The token rode in via argv; if the CLI echoed the command back in its error,
+            # keep the secret out of the message we print / return as JSON.
+            raise CLIError("claude mcp add failed: " + (_redact_token(detail, token) or "unknown error"))
+
+    # -- File fallback ------------------------------------------------------------
+
+    def _write_config_file(self, path: Path, server_name: str, url: str, token: Optional[str]) -> WriteResult:
+        entry: Dict[str, Any] = {"type": "http", "url": url}
+        if token:
+            entry["headers"] = {"Authorization": bearer_header(token)}
+        write_servers_entry(path, server_name, entry, secure=bool(token))
+        note = None
+        if path == self._project_config_path and token:
+            note = str(path) + " is project-scoped and often committed to version control; it now contains a token."
+        return WriteResult(method="file", location=str(path), note=note)

agnoctl/clients/claude_desktop.py

@@ -0,0 +1,141 @@
+"""Claude Desktop adapter.
+
+Claude Desktop reads MCP servers from claude_desktop_config.json, but that file is
+stdio-only: it launches each server as a subprocess and speaks JSON-RPC over stdio, so
+it cannot point at a remote HTTP AgentOS directly. The supported bridge is `mcp-remote`
+(run via npx), a small stdio<->HTTP proxy that every remote-MCP vendor documents for
+this client. We write an entry that launches it with the AgentOS URL and, when auth is
+on, an Authorization header sourced from an env var so the token stays out of argv:
+
+    "agno": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "<url>", "--header", "Authorization:${AGNO_AUTH_HEADER}"],
+      "env": {"AGNO_AUTH_HEADER": "Bearer <token>"}
+    }
+
+Config path is per-OS (macOS Application Support, Windows APPDATA, Linux ~/.config).
+Because the bridge runs at Claude Desktop launch time, it needs Node/npx on PATH; connect
+verifies the AgentOS endpoint itself, not that Claude can spawn npx, so a missing npx is
+surfaced as a note rather than a failure.
+"""
+
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from agnoctl.clients.base import (
+    ClientAdapter,
+    ExistingEntry,
+    WriteResult,
+    bearer_header,
+    read_json_lenient,
+    servers_table,
+    token_from_authorization,
+    write_servers_entry,
+)
+
+# The env var the written entry reads the Authorization header from.
+AUTH_ENV_VAR = "AGNO_AUTH_HEADER"
+
+_ENV_REF = re.compile(r"\$\{(\w+)\}")
+
+
+def _default_config_path(home: Path, platform: str) -> Path:
+    if platform == "darwin":
+        return home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if platform.startswith("win"):
+        appdata = os.environ.get("APPDATA")
+        base = Path(appdata) if appdata else home / "AppData" / "Roaming"
+        return base / "Claude" / "claude_desktop_config.json"
+    return home / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def _resolve_env_refs(value: str, env: Dict[str, Any]) -> str:
+    """Expand ${VAR} references against the entry's own env table."""
+
+    def repl(match: "re.Match[str]") -> str:
+        replacement = env.get(match.group(1))
+        return replacement if isinstance(replacement, str) else match.group(0)
+
+    return _ENV_REF.sub(repl, value)
+
+
+def _token_from_bridge(args: List[Any], env: Dict[str, Any]) -> Optional[str]:
+    """Pull the bearer token out of a `--header Authorization:...` mcp-remote arg."""
+    for i, arg in enumerate(args):
+        if arg == "--header" and i + 1 < len(args) and isinstance(args[i + 1], str):
+            name, sep, raw = args[i + 1].partition(":")
+            if sep and name.strip().lower() == "authorization":
+                return token_from_authorization(_resolve_env_refs(raw.strip(), env))
+    return None
+
+
+def _entry_from_config(entry: Any, location: str) -> Optional[ExistingEntry]:
+    if not isinstance(entry, dict):
+        return None
+    # Forward-compatible: if a future Claude Desktop writes a native remote entry.
+    url = entry.get("url")
+    if isinstance(url, str) and url:
+        headers = entry.get("headers")
+        header_map = headers if isinstance(headers, dict) else {}
+        return ExistingEntry(
+            url=url, token=token_from_authorization(header_map.get("Authorization")), location=location
+        )
+    # The mcp-remote bridge: first http(s) arg is the AgentOS URL.
+    args = entry.get("args")
+    if not isinstance(args, list):
+        return None
+    bridge_url = next(
+        (a for a in args if isinstance(a, str) and (a.startswith("http://") or a.startswith("https://"))), None
+    )
+    if not bridge_url:
+        return None
+    env = entry.get("env")
+    env_map = env if isinstance(env, dict) else {}
+    return ExistingEntry(url=bridge_url, token=_token_from_bridge(args, env_map), location=location)
+
+
+class ClaudeDesktopAdapter(ClientAdapter):
+    key = "claude-desktop"
+
+    def __init__(
+        self,
+        home: Optional[Path] = None,
+        config_path: Optional[Path] = None,
+        platform: str = sys.platform,
+        which: Callable[[str], Optional[str]] = shutil.which,
+    ):
+        self.home = home or Path.home()
+        self._config_path = config_path or _default_config_path(self.home, platform)
+        self._which = which
+
+    @property
+    def config_path(self) -> Path:
+        return self._config_path
+
+    def detect(self) -> bool:
+        return self.config_path.exists() or self.config_path.parent.is_dir()
+
+    def read_existing(self, server_name: str) -> Optional[ExistingEntry]:
+        config = read_json_lenient(self.config_path)
+        if config is None:
+            return None
+        return _entry_from_config(servers_table(config).get(server_name), str(self.config_path))
+
+    def write(self, server_name: str, url: str, token: Optional[str]) -> WriteResult:
+        args: List[str] = ["-y", "mcp-remote", url]
+        entry: Dict[str, Any] = {"command": "npx", "args": args}
+        if token:
+            args += ["--header", "Authorization:${" + AUTH_ENV_VAR + "}"]
+            entry["env"] = {AUTH_ENV_VAR: bearer_header(token)}
+        write_servers_entry(self.config_path, server_name, entry, secure=bool(token), mkdir=True)
+
+        note = None
+        if self._which("npx") is None:
+            note = (
+                "Claude Desktop launches this server with 'npx mcp-remote'; install Node.js/npx or it will not start."
+            )
+        return WriteResult(method="file", location=str(self.config_path), note=note)

agnoctl/clients/codex.py

@@ -0,0 +1,166 @@
+"""OpenAI Codex adapter.
+
+Codex reads MCP servers from ~/.codex/config.toml as [mcp_servers.<name>] tables. The
+`codex mcp add` CLI cannot set static HTTP headers (only --bearer-token-env-var, which
+requires the user to manage an environment variable), so this adapter edits the config
+file directly, using a static http_headers table for zero-setup authentication.
+
+The edit is a section-scoped text replacement: only lines belonging to
+[mcp_servers.<name>] (and its dotted subtables) are touched, so user comments and other
+servers survive. The result is validated by re-parsing before it is written.
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from agnoctl.clients.base import (
+    ClientAdapter,
+    ExistingEntry,
+    WriteResult,
+    atomic_write_text,
+    bearer_header,
+    token_from_authorization,
+)
+from agnoctl.errors import CLIError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+def _toml_string(value: str) -> str:
+    # TOML basic strings share JSON's escaping rules for the characters that matter here.
+    return json.dumps(value)
+
+
+class CodexAdapter(ClientAdapter):
+    key = "codex"
+
+    def __init__(self, home: Optional[Path] = None):
+        self.home = home or Path.home()
+
+    @property
+    def config_path(self) -> Path:
+        return self.home / ".codex" / "config.toml"
+
+    def detect(self) -> bool:
+        return (self.home / ".codex").is_dir()
+
+    def read_existing(self, server_name: str) -> Optional[ExistingEntry]:
+        parsed = self._parse_config()
+        if parsed is None:
+            return None
+        entry = (parsed.get("mcp_servers") or {}).get(server_name)
+        if not isinstance(entry, dict):
+            return None
+        url = entry.get("url")
+        if not isinstance(url, str) or not url:
+            return None
+        headers = entry.get("http_headers")
+        if not isinstance(headers, dict):
+            headers = {}
+        return ExistingEntry(
+            url=url,
+            token=token_from_authorization(headers.get("Authorization")),
+            location=str(self.config_path),
+        )
+
+    def write(self, server_name: str, url: str, token: Optional[str]) -> WriteResult:
+        block_lines = ["[mcp_servers." + server_name + "]", "url = " + _toml_string(url)]
+        if token:
+            block_lines.append(
+                "http_headers = { " + _toml_string("Authorization") + " = " + _toml_string(bearer_header(token)) + " }"
+            )
+        block = "\n".join(block_lines) + "\n"
+
+        existing_text = self.config_path.read_text() if self.config_path.exists() else ""
+        if existing_text:
+            try:
+                tomllib.loads(existing_text)
+            except tomllib.TOMLDecodeError as e:
+                raise CLIError(
+                    "Refusing to modify "
+                    + str(self.config_path)
+                    + ": the existing TOML does not parse ("
+                    + str(e)
+                    + ").",
+                    hint="Fix or move the file, then re-run.",
+                )
+        new_text = self._replace_section(existing_text, server_name, block)
+
+        try:
+            tomllib.loads(new_text)
+        except tomllib.TOMLDecodeError as e:
+            raise CLIError(
+                "Refusing to write " + str(self.config_path) + ": the resulting TOML would be invalid (" + str(e) + ")."
+            )
+
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(self.config_path, new_text, secure=bool(token))
+        return WriteResult(method="file", location=str(self.config_path))
+
+    # -- Internals -----------------------------------------------------------------
+
+    def _parse_config(self) -> Optional[Dict[str, Any]]:
+        if not self.config_path.exists():
+            return None
+        try:
+            return tomllib.loads(self.config_path.read_text())
+        except (OSError, tomllib.TOMLDecodeError):
+            return None
+
+    @staticmethod
+    def _replace_section(text: str, server_name: str, block: str) -> str:
+        """Replace (or append) the [mcp_servers.<name>] section, including dotted subtables.
+
+        Every table header — [table] and [[array-of-tables]] alike — ends the previous
+        section, so content following the managed section is never swallowed. Trailing
+        comment/blank lines inside the managed section that lead into the next header
+        are preserved, since they usually describe what follows.
+        """
+        section_prefix = "[mcp_servers." + server_name
+        lines = text.splitlines()
+        kept: List[str] = []
+        dropped: List[str] = []
+        insert_at: Optional[int] = None
+        in_section = False
+
+        def flush_trailing_comments() -> None:
+            trailing: List[str] = []
+            for dropped_line in reversed(dropped):
+                if dropped_line.strip() == "" or dropped_line.lstrip().startswith("#"):
+                    trailing.append(dropped_line)
+                else:
+                    break
+            kept.extend(reversed(trailing))
+            dropped.clear()
+
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("["):
+                owns = stripped.startswith(section_prefix + "]") or stripped.startswith(section_prefix + ".")
+                if in_section and not owns:
+                    flush_trailing_comments()
+                in_section = owns
+                if owns:
+                    if insert_at is None:
+                        insert_at = len(kept)
+                    continue
+            if in_section:
+                dropped.append(line)
+            else:
+                kept.append(line)
+        if in_section:
+            dropped.clear()
+
+        block_lines = block.rstrip("\n").splitlines()
+        if insert_at is not None:
+            kept[insert_at:insert_at] = block_lines
+        else:
+            if kept and kept[-1].strip():
+                kept.append("")
+            kept.extend(block_lines)
+        return "\n".join(kept).rstrip("\n") + "\n"