agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/schemas/io/config_io.py

@@ -0,0 +1,458 @@
+"""Read/validate/write AgentCore config files (port of ``config-io.ts``).
+
+Schema models come from ``agentcore.schema`` and are imported lazily. Reads return validated
+Pydantic models; writes accept models or plain dicts, validate, and write
+``JSON.stringify(data, null, 2)``-identical output (2-space indent, no trailing newline)
+atomically through a sibling temp file + rename.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any, Literal, TypeVar
+
+from pydantic import BaseModel, TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+
+from agentcore.lib.errors.types import (
+    ConfigNotFoundError,
+    ConfigParseError,
+    ConfigReadError,
+    ConfigValidationError,
+    ConfigWriteError,
+    NoProjectError,
+)
+from agentcore.lib.schemas.io.path_resolver import PathConfig, PathResolver, find_config_root
+from agentcore.lib.utils.aws_account import detect_aws_account
+from agentcore.lib.utils.json_format import to_json_string
+
+T = TypeVar("T")
+
+SchemaVersion = Literal[1]
+
+PROJECT_LOCK_RETRY_MS = 25
+PROJECT_LOCK_TIMEOUT_MS = 45_000
+PROJECT_LOCK_STALE_MS = 60_000
+
+# Mirrors AgentCoreRegionSchema; used only if agentcore.schema doesn't expose the region type.
+_FALLBACK_REGIONS = frozenset(
+    {
+        "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-south-2", "ap-southeast-1", "ap-southeast-2",
+        "ap-southeast-5", "ap-southeast-7", "ca-central-1", "eu-central-1", "eu-north-1", "eu-south-1",
+        "eu-south-2", "eu-west-1", "eu-west-2", "eu-west-3", "sa-east-1", "us-east-1", "us-east-2",
+        "us-west-1", "us-west-2", "us-gov-west-1",
+    }
+)  # fmt: skip
+
+
+def get_schema_url_for_version(version: SchemaVersion) -> str:
+    return f"https://schema.agentcore.aws.dev/v{version}/agentcore.json"
+
+
+# --- Schema bridge -----------------------------------------------------------------------------
+
+Validator = type[BaseModel] | TypeAdapter[Any]
+
+
+def _schema_attr(name: str) -> Any:
+    import agentcore.schema as schema
+
+    try:
+        return getattr(schema, name)
+    except AttributeError as exc:
+        raise ImportError(f"agentcore.schema does not define {name}") from exc
+
+
+def _targets_validator() -> Validator:
+    try:
+        import agentcore.schema as schema
+
+        adapter = getattr(schema, "AwsDeploymentTargetsSchema", None)
+    except ImportError:
+        adapter = None
+    if isinstance(adapter, TypeAdapter) or (isinstance(adapter, type) and issubclass(adapter, BaseModel)):
+        return adapter
+    return TypeAdapter(list[_schema_attr("AwsDeploymentTarget")])  # type: ignore[misc]
+
+
+def to_jsonable(value: Any) -> Any:
+    """Models -> ``model_dump(mode="json", by_alias=True)``, recursively.
+
+    Not ``exclude_none``: the schema models already omit unset optionals, and ``exclude_none``
+    would also strip ``null``s inside free-form payloads that upstream preserves.
+    """
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json", by_alias=True)
+    if isinstance(value, Mapping):
+        return {k: to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(v) for v in value]
+    return value
+
+
+def _run_validator(validator: Validator, data: Any) -> Any:
+    if isinstance(validator, TypeAdapter):
+        return validator.validate_python(data)
+    return validator.model_validate(data)
+
+
+def _dump(validator: Validator, value: Any) -> Any:
+    if isinstance(validator, TypeAdapter):
+        return validator.dump_python(value, mode="json", by_alias=True)
+    return to_jsonable(value)
+
+
+def _unique_by_name(items: Any, message: Callable[[str], str]) -> list[dict[str, Any]]:
+    issues: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for idx, item in enumerate(items or []):
+        name = item.get("name") if isinstance(item, Mapping) else getattr(item, "name", None)
+        if name in seen:
+            issues.append({"type": "custom", "loc": (idx,), "msg": message(str(name))})
+        seen.add(name)
+    return issues
+
+
+class ConfigIO:
+    """Reads, writes and validates AgentCore configuration files."""
+
+    def __init__(self, path_config: PathConfig | Mapping[str, str] | None = None, *, base_dir: str | None = None):
+        if isinstance(path_config, Mapping):
+            base_dir = base_dir or path_config.get("base_dir") or path_config.get("baseDir")
+        elif isinstance(path_config, PathConfig):
+            base_dir = base_dir or path_config.base_dir
+
+        if base_dir:
+            # Explicit base dir (e.g. during project creation).
+            self._project_discovered = True
+        else:
+            discovered = find_config_root()
+            base_dir = discovered
+            self._project_discovered = discovered is not None
+
+        self._path_resolver = PathResolver(base_dir=base_dir)
+
+    def has_project(self) -> bool:
+        """False when no base dir was given and auto-discovery found no project."""
+        return self._project_discovered
+
+    def get_path_resolver(self) -> PathResolver:
+        return self._path_resolver
+
+    def set_base_dir(self, base_dir: str) -> None:
+        self._path_resolver.set_base_dir(base_dir)
+
+    def get_project_root(self) -> str:
+        return self._path_resolver.get_project_root()
+
+    def get_config_root(self) -> str:
+        return self._path_resolver.get_base_dir()
+
+    def get_agent_config_path(self) -> str:
+        return self._path_resolver.get_agent_config_path()
+
+    def get_harness_config_path(self, harness_name: str) -> str:
+        return self._path_resolver.get_harness_config_path(harness_name)
+
+    # --- Project spec ---
+
+    def read_project_spec(self) -> Any:
+        return self._read_and_validate(
+            self._path_resolver.get_agent_config_path(),
+            "AgentCore Project Config",
+            _schema_attr("AgentCoreProjectSpec"),
+        )
+
+    def write_project_spec(self, data: Any) -> None:
+        cleaned = to_jsonable(data)
+        # TODO (upstream): extend to all resource arrays so empty defaults never pollute agentcore.json
+        if isinstance(cleaned, dict):
+            for key in ("configBundles", "abTests"):
+                if cleaned.get(key) == []:
+                    del cleaned[key]
+        self._validate_and_write(
+            self._path_resolver.get_agent_config_path(),
+            "AgentCore Project Config",
+            _schema_attr("AgentCoreProjectSpec"),
+            cleaned,
+        )
+
+    def update_project_spec(self, mutate: Callable[[Any], Any]) -> Any:
+        """Read, mutate, validate and write ``agentcore.json`` under a cross-process lock.
+
+        ``mutate`` may modify the project in place (returning ``None``) or return a replacement.
+        """
+        with self._file_lock(self._path_resolver.get_agent_config_path()):
+            project = self.read_project_spec()
+            result = mutate(project)
+            updated = project if result is None else result
+            self.write_project_spec(updated)
+            return updated
+
+    # --- AWS targets ---
+
+    def read_aws_deployment_targets(self) -> list[Any]:
+        """Read ``aws-targets.json``. With ``AWS_PROFILE`` set, the account comes from the credentials."""
+        targets = self._read_targets()
+        if os.environ.get("AWS_PROFILE"):
+            account = detect_aws_account()
+            if account:
+                targets = [_with_field(t, "account", account) for t in targets]
+        return targets
+
+    def resolve_aws_deployment_targets(self) -> list[Any]:
+        """Targets with region fallback: saved > AWS_REGION > AWS_DEFAULT_REGION > profile config."""
+        targets = self.read_aws_deployment_targets()
+        fallback_region = self._resolve_region_fallback()
+        if not fallback_region:
+            return targets
+        return [t if _get_field(t, "region") else _with_field(t, "region", fallback_region) for t in targets]
+
+    def _resolve_region_fallback(self) -> str | None:
+        env_region = os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+        if env_region and _is_agentcore_region(env_region):
+            return env_region
+        try:
+            import botocore.session
+
+            profile = os.environ.get("AWS_PROFILE") or "default"
+            profiles = botocore.session.Session().full_config.get("profiles", {})
+            profile_region = profiles.get(profile, {}).get("region")
+            if profile_region and _is_agentcore_region(profile_region):
+                return profile_region
+        except Exception:
+            pass  # config file not available
+        return None
+
+    def write_aws_deployment_targets(self, data: Sequence[Any]) -> None:
+        file_path = self._path_resolver.get_aws_targets_config_path()
+
+        def check(targets: Any) -> None:
+            issues = _unique_by_name(_as_list(targets), lambda n: f"Duplicate deployment target name: {n}")
+            if issues:
+                raise ConfigValidationError(file_path, "AWS Targets", issues)
+
+        self._validate_and_write(file_path, "AWS Targets", _targets_validator(), list(data), check=check)
+
+    def _read_targets(self) -> list[Any]:
+        file_path = self._path_resolver.get_aws_targets_config_path()
+        targets = self._read_and_validate(file_path, "AWS Targets", _targets_validator())
+        targets = _as_list(targets)
+        issues = _unique_by_name(targets, lambda n: f"Duplicate deployment target name: {n}")
+        if issues:
+            raise ConfigValidationError(file_path, "AWS Targets", issues)
+        return targets
+
+    # --- Deployed state ---
+
+    def _target_names(self) -> set[str]:
+        return {str(_get_field(t, "name")) for t in self.read_aws_deployment_targets()}
+
+    def read_deployed_state(self) -> Any:
+        """Read ``.cli/deployed-state.json``; every target key must exist in aws-targets."""
+        names = self._target_names()
+        file_path = self._path_resolver.get_state_path()
+        state = self._read_and_validate(file_path, "State", _schema_attr("DeployedState"))
+        self._check_state_targets(file_path, state, names)
+        return state
+
+    def write_deployed_state(self, data: Any) -> None:
+        names = self._target_names()
+        file_path = self._path_resolver.get_state_path()
+        self._validate_and_write(
+            file_path,
+            "State",
+            _schema_attr("DeployedState"),
+            data,
+            check=lambda state: self._check_state_targets(file_path, state, names),
+        )
+
+    def _check_state_targets(self, file_path: str, state: Any, names: set[str]) -> None:
+        targets = _get_field(state, "targets")
+        keys = list(targets.keys()) if isinstance(targets, Mapping) else []
+        if all(k in names for k in keys):
+            return
+        raise ConfigValidationError(
+            file_path,
+            "State",
+            [{"type": "custom", "loc": (), "msg": "Deployed state contains target names not present in aws-targets"}],
+        )
+
+    # --- MCP defs / harness ---
+
+    def read_mcp_defs(self) -> Any:
+        return self._read_and_validate(
+            self._path_resolver.get_mcp_defs_path(), "MCP Definitions", _schema_attr("AgentCoreCliMcpDefs")
+        )
+
+    def write_mcp_defs(self, data: Any) -> None:
+        self._validate_and_write(
+            self._path_resolver.get_mcp_defs_path(), "MCP Definitions", _schema_attr("AgentCoreCliMcpDefs"), data
+        )
+
+    def read_harness_spec(self, harness_name: str) -> Any:
+        return self._read_and_validate(
+            self._path_resolver.get_harness_config_path(harness_name), "Harness Spec", _schema_attr("HarnessSpec")
+        )
+
+    def write_harness_spec(self, harness_name: str, data: Any) -> None:
+        self._validate_and_write(
+            self._path_resolver.get_harness_config_path(harness_name), "Harness Spec", _schema_attr("HarnessSpec"), data
+        )
+
+    # --- Existence / init ---
+
+    def base_dir_exists(self) -> bool:
+        return os.path.exists(self._path_resolver.get_base_dir())
+
+    def config_exists(self, kind: Literal["project", "awsTargets", "state", "mcpDefs"]) -> bool:
+        paths = {
+            "project": self._path_resolver.get_agent_config_path,
+            "awsTargets": self._path_resolver.get_aws_targets_config_path,
+            "state": self._path_resolver.get_state_path,
+            "mcpDefs": self._path_resolver.get_mcp_defs_path,
+        }
+        return os.path.exists(paths[kind]())
+
+    def initialize_base_dir(self) -> None:
+        """Create ``agentcore/`` and ``agentcore/.cli/``. Requires a configured/discovered project."""
+        self._require_project()
+        base_dir = self._path_resolver.get_base_dir()
+        try:
+            os.makedirs(base_dir, exist_ok=True)
+            os.makedirs(self._path_resolver.get_cli_system_dir(), exist_ok=True)
+        except OSError as exc:
+            raise ConfigWriteError(base_dir, exc) from exc
+
+    # --- Internals ---
+
+    def _require_project(self) -> None:
+        if not self._project_discovered:
+            raise NoProjectError()
+
+    def _read_and_validate(self, file_path: str, file_type: str, validator: Validator) -> Any:
+        if not os.path.exists(file_path):
+            raise ConfigNotFoundError(file_path, file_type)
+        try:
+            with open(file_path, encoding="utf-8") as fh:
+                content = fh.read()
+        except (OSError, UnicodeDecodeError) as exc:
+            raise ConfigReadError(file_path, exc) from exc
+        try:
+            parsed = json.loads(content)
+        except ValueError as exc:
+            raise ConfigParseError(file_path, exc) from exc
+        try:
+            return _run_validator(validator, parsed)
+        except PydanticValidationError as exc:
+            raise ConfigValidationError(file_path, file_type, exc) from exc
+
+    def _validate_and_write(
+        self,
+        file_path: str,
+        file_type: str,
+        validator: Validator,
+        data: Any,
+        check: Callable[[Any], None] | None = None,
+    ) -> None:
+        self._require_project()
+        try:
+            validated = _run_validator(validator, to_jsonable(data))
+        except PydanticValidationError as exc:
+            raise ConfigValidationError(file_path, file_type, exc) from exc
+        if check is not None:
+            check(validated)
+
+        try:
+            os.makedirs(os.path.dirname(file_path), exist_ok=True)
+        except OSError as exc:
+            raise ConfigWriteError(file_path, exc) from exc
+
+        # Write a sibling temp file and rename so readers never observe partial JSON.
+        temp_path = f"{file_path}.{os.getpid()}.{uuid.uuid4()}.tmp"
+        try:
+            content = to_json_string(_dump(validator, validated), 2)
+            with open(temp_path, "w", encoding="utf-8", newline="") as fh:
+                fh.write(content)
+            os.replace(temp_path, file_path)
+        except Exception as exc:
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            raise ConfigWriteError(file_path, exc) from exc
+
+    @contextmanager
+    def _file_lock(self, file_path: str):  # type: ignore[no-untyped-def]
+        """Exclusive ``<file>.lock`` via O_EXCL; stale locks (>60s) are broken, waits time out at 45s."""
+        lock_path = f"{file_path}.lock"
+        started = time.monotonic()
+        fd: int | None = None
+        while fd is None:
+            try:
+                fd = os.open(lock_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+            except FileExistsError:
+                try:
+                    if time.time() - os.stat(lock_path).st_mtime > PROJECT_LOCK_STALE_MS / 1000:
+                        os.unlink(lock_path)
+                        continue
+                except FileNotFoundError:
+                    continue
+                except OSError as exc:
+                    raise ConfigWriteError(file_path, exc) from exc
+                if (time.monotonic() - started) * 1000 >= PROJECT_LOCK_TIMEOUT_MS:
+                    raise ConfigWriteError(
+                        file_path, RuntimeError("Timed out waiting for another configuration update")
+                    ) from None
+                time.sleep(PROJECT_LOCK_RETRY_MS / 1000)
+            except OSError as exc:
+                raise ConfigWriteError(file_path, exc) from exc
+        try:
+            yield
+        finally:
+            os.close(fd)
+            try:
+                os.unlink(lock_path)
+            except FileNotFoundError:
+                pass
+
+
+def _as_list(value: Any) -> list[Any]:
+    return list(value.root) if hasattr(value, "root") else list(value)
+
+
+def _get_field(obj: Any, key: str) -> Any:
+    if isinstance(obj, Mapping):
+        return obj.get(key)
+    return getattr(obj, key, None)
+
+
+def _with_field(obj: Any, key: str, value: Any) -> Any:
+    if isinstance(obj, BaseModel):
+        return obj.model_copy(update={key: value})
+    if isinstance(obj, Mapping):
+        return {**obj, key: value}
+    return obj
+
+
+def _is_agentcore_region(region: str) -> bool:
+    try:
+        region_type = _schema_attr("AgentCoreRegion")
+    except ImportError:
+        return region in _FALLBACK_REGIONS
+    try:
+        TypeAdapter(region_type).validate_python(region)
+        return True
+    except PydanticValidationError:
+        return False
+    except Exception:
+        return region in _FALLBACK_REGIONS
+
+
+def create_config_io(path_config: PathConfig | Mapping[str, str] | None = None, **kwargs: Any) -> ConfigIO:
+    return ConfigIO(path_config, **kwargs)

agentcore/lib/schemas/io/global_config.py

@@ -0,0 +1,239 @@
+"""User-level CLI config at ``~/.agentcore/config.json`` (port of ``global-config.ts``).
+
+The config is a plain ``dict`` keyed by the on-disk camelCase names. Reads are resilient
+(invalid fields are dropped, unknown keys preserved); ``validate_global_config`` is strict.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, NotRequired, TypedDict
+
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.utils.json_format import to_json_string
+
+
+class TelemetryConfig(TypedDict, total=False):
+    enabled: bool
+    endpoint: str
+    audit: bool
+
+
+class GlobalConfig(TypedDict, total=False):
+    installationId: str
+    uvDefaultIndex: str
+    uvIndex: str
+    disableDependencyManagement: bool
+    disableTransactionSearch: bool
+    transactionSearchIndexPercentage: int
+    telemetry: NotRequired[TelemetryConfig]
+
+
+def get_global_config_dir() -> str:
+    env_dir = os.environ.get("AGENTCORE_CONFIG_DIR")
+    return env_dir if env_dir is not None else os.path.join(os.path.expanduser("~"), ".agentcore")
+
+
+def get_global_config_file() -> str:
+    return os.path.join(get_global_config_dir(), "config.json")
+
+
+# Snapshot at import time, like upstream. Functions resolve the location at call time instead
+# so AGENTCORE_CONFIG_DIR changes (e.g. in tests) take effect.
+GLOBAL_CONFIG_DIR = get_global_config_dir()
+GLOBAL_CONFIG_FILE = get_global_config_file()
+
+
+# --- Schema (strict, mirrors the Zod object) --------------------------------------------------
+
+# Zod 4's z.string().uuid() pattern.
+_UUID_RE = re.compile(
+    r"([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}"
+    r"|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)"
+)
+
+
+class _Invalid(Exception):
+    pass
+
+
+def _string(value: Any) -> str:
+    if not isinstance(value, str):
+        raise _Invalid("expected string")
+    return value
+
+
+def _uuid(value: Any) -> str:
+    if not isinstance(value, str) or not _UUID_RE.fullmatch(value):
+        raise _Invalid("Invalid UUID")
+    return value
+
+
+def _boolean(value: Any) -> bool:
+    if not isinstance(value, bool):
+        raise _Invalid("expected boolean")
+    return value
+
+
+def _percentage(value: Any) -> int:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise _Invalid("expected number")
+    if isinstance(value, float) and not value.is_integer():
+        raise _Invalid("expected int, received number")
+    if not 0 <= value <= 100:
+        raise _Invalid("Too small: expected number to be >=0" if value < 0 else "Too big: expected number to be <=100")
+    return int(value)
+
+
+_Validator = Callable[[Any], Any]
+
+_TELEMETRY_SHAPE: dict[str, _Validator] = {"enabled": _boolean, "endpoint": _string, "audit": _boolean}
+
+
+def _strict_object(shape: Mapping[str, Any], value: Any, path: list[Any], issues: list[dict[str, Any]]) -> None:
+    if not isinstance(value, Mapping):
+        issues.append({"type": "dict_type", "loc": tuple(path), "msg": "expected object"})
+        return
+    for key, item in value.items():
+        if key not in shape:
+            issues.append({"type": "extra_forbidden", "loc": (*path, key), "msg": "Unrecognized key"})
+            continue
+        validator = shape[key]
+        if isinstance(validator, Mapping):
+            _strict_object(validator, item, [*path, key], issues)
+            continue
+        try:
+            validator(item)
+        except _Invalid as exc:
+            issues.append({"type": "value_error", "loc": (*path, key), "msg": str(exc), "input": item})
+
+
+_GLOBAL_SHAPE: dict[str, Any] = {
+    "installationId": _uuid,
+    "uvDefaultIndex": _string,
+    "uvIndex": _string,
+    "disableDependencyManagement": _boolean,
+    "disableTransactionSearch": _boolean,
+    "transactionSearchIndexPercentage": _percentage,
+    "telemetry": _TELEMETRY_SHAPE,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class GlobalConfigValidation:
+    success: bool
+    issues: list[dict[str, Any]] = field(default_factory=list)
+
+
+def validate_global_config(data: Any) -> GlobalConfigValidation:
+    """Strictly validate a (partial) config: unknown keys and wrong types fail."""
+    issues: list[dict[str, Any]] = []
+    _strict_object(_GLOBAL_SHAPE, data, [], issues)
+    return GlobalConfigValidation(success=not issues, issues=issues)
+
+
+def _resilient(shape: Mapping[str, Any], data: Any) -> dict[str, Any]:
+    """Field-by-field parse: invalid known fields are dropped, unknown keys kept (upstream resilientParse)."""
+    if not isinstance(data, Mapping):
+        return {}
+    result: dict[str, Any] = {}
+    for key, validator in shape.items():
+        if key not in data:
+            continue
+        value = data[key]
+        if isinstance(validator, Mapping):
+            if isinstance(value, Mapping):
+                result[key] = _resilient(validator, value)
+            continue
+        try:
+            result[key] = validator(value)
+        except _Invalid:
+            pass
+    for key, value in data.items():
+        if key not in shape:
+            result[key] = value
+    return result
+
+
+# --- I/O ---------------------------------------------------------------------------------------
+
+
+def read_global_config(config_file: str | None = None) -> Ok[GlobalConfig] | Err[Exception]:
+    """Read the config. A missing file is ``Ok({})``; an unreadable/unparseable file is ``Err``."""
+    path = config_file or get_global_config_file()
+    if not os.path.exists(path):
+        return Ok(GlobalConfig())
+    try:
+        with open(path, encoding="utf-8") as fh:
+            parsed = json.load(fh)
+        if not isinstance(parsed, dict):
+            return Err(ValueError(f"Config at {path} is not a JSON object."))
+        return Ok(_resilient(_GLOBAL_SHAPE, parsed))  # type: ignore[arg-type]
+    except Exception as exc:
+        return Err(exc)
+
+
+def read_global_config_sync(config_file: str | None = None) -> GlobalConfig:
+    """Best-effort read; any failure yields ``{}``."""
+    try:
+        with open(config_file or get_global_config_file(), encoding="utf-8") as fh:
+            return _resilient(_GLOBAL_SHAPE, json.load(fh))  # type: ignore[return-value]
+    except Exception:
+        return GlobalConfig()
+
+
+def _merge_config(target: Mapping[str, Any], source: Mapping[str, Any]) -> dict[str, Any]:
+    merged = {**target, **source}
+    if "telemetry" in source:
+        merged["telemetry"] = {**(target.get("telemetry") or {}), **(source["telemetry"] or {})}
+    return merged
+
+
+def update_global_config(
+    partial: Mapping[str, Any], config_dir: str | None = None, config_file: str | None = None
+) -> bool:
+    """Shallow-merge ``partial`` into the config (``telemetry`` merged one level deep)."""
+    config_dir = config_dir or get_global_config_dir()
+    config_file = config_file or get_global_config_file()
+    existing = read_global_config(config_file)
+    if not isinstance(existing, Ok):
+        return False
+    try:
+        merged = _merge_config(existing.value, partial)
+        os.makedirs(config_dir, exist_ok=True)
+        with open(config_file, "w", encoding="utf-8") as fh:
+            fh.write(to_json_string(merged, 2))
+        return True
+    except Exception:
+        return False
+
+
+@dataclass(frozen=True, slots=True)
+class InstallationId:
+    id: str
+    created: bool
+
+
+def get_or_create_installation_id(
+    config_dir: str | None = None, config_file: str | None = None
+) -> Ok[InstallationId] | Err[Exception]:
+    """Return the installation id, generating and persisting one if absent or not a valid UUID.
+
+    Concurrent first runs may each generate an id; the last write wins.
+    """
+    config_file = config_file or get_global_config_file()
+    read = read_global_config(config_file)
+    if not isinstance(read, Ok):
+        return read
+    existing = read.value.get("installationId")
+    if existing:
+        return Ok(InstallationId(id=existing, created=False))
+    new_id = str(uuid.uuid4())
+    if not update_global_config({"installationId": new_id}, config_dir, config_file):
+        return Err(RuntimeError(f"Failed to persist installation id to {config_file}"))
+    return Ok(InstallationId(id=new_id, created=True))