@event4u/agent-config 1.41.2 → 2.1.0

package/scripts/_lib/agent_settings.py

@@ -3,17 +3,24 @@
 Phase 1 of road-to-portable-dev-preferences. Single source of truth for
 how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
-Resolution order (project wins, user-global fills gaps for whitelisted
-keys only):
+Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  1. Project ``./.agent-settings.yml``                  (full file, all keys)
-  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
-  3. Built-in defaults                                  (currently empty)
+  N. ``~/.config/agent-config/agent-settings.yml``  (user-global; whitelist only)
+N-1. ``<repo-root>/.agent-settings.yml``            (project-wide; all keys)
+N-2. ``<intermediate-dir>/.agent-settings.yml``     (subsystem-scoped; all keys)
+  1. ``<CWD>/.agent-settings.yml``                  (deepest, wins; all keys)
+
+``<repo-root>`` is the nearest ancestor that contains ``.git`` (directory
+**or** file — submodule support). The walk stops there — it never drifts
+into a parent repo or ``$HOME``. When ``cwd`` is ``None`` (default), the
+loader behaves identically to the pre-cascade contract: project file +
+user-global only, no ancestor walk. Back-compat is hard.
 
 Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
 non-whitelisted key in the user-global file is silently ignored — the
 ``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
-debugging.
+debugging. Non-root in-project layers (intermediate + CWD) are **not**
+whitelist-filtered — they live inside the project boundary.
 
 Contract — pure, read-only, tolerant:
 
@@ -28,7 +35,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 logger = logging.getLogger(__name__)
 
@@ -53,10 +60,70 @@ MERGEABLE_KEYS: tuple[str, ...] = (
 _DEFAULTS: dict[str, Any] = {}
 
 
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from ``start`` looking for ``.git`` (file or directory).
+
+    Returns the first ancestor that contains ``.git`` as a file (submodule
+    pointer) or directory (regular checkout), or ``None`` if the walk
+    reaches the filesystem root without finding one. The walk stops at
+    the project boundary — it never drifts into a parent repo or
+    ``$HOME``.
+
+    Pure read-only; never touches the filesystem beyond ``exists()``
+    probes on the ``.git`` entry.
+    """
+    current = start.resolve() if start.exists() else start
+    # ``Path.parents`` excludes ``current`` itself, so probe it first.
+    for candidate in [current, *current.parents]:
+        git_marker = candidate / ".git"
+        if git_marker.exists():
+            return candidate
+    return None
+
+
+def _resolve_cascade_paths(
+    cwd: Path | None,
+    project_path: Path | str | None,
+) -> list[Path]:
+    """Return the ordered cascade of in-project settings files (shallow → deep).
+
+    When ``cwd`` is provided and ``find_project_root(cwd)`` succeeds, the
+    list contains every ``<dir>/.agent-settings.yml`` from the repo root
+    down to ``cwd`` (inclusive on both ends), shallowest first. When
+    ``cwd`` is ``None`` or no ``.git`` is reached, falls back to the
+    single legacy project path — back-compat with the pre-cascade
+    loader.
+    """
+    if cwd is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    root = find_project_root(cwd)
+    if root is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    cwd_resolved = cwd.resolve()
+    # Build the chain root → … → cwd (shallowest first, deepest last).
+    chain: list[Path] = []
+    cursor = cwd_resolved
+    while True:
+        chain.append(cursor)
+        if cursor == root:
+            break
+        parent = cursor.parent
+        if parent == cursor:
+            break
+        cursor = parent
+    chain.reverse()
+    return [d / DEFAULT_PROJECT_FILE for d in chain]
+
+
 def load_agent_settings(
     project_path: Path | str | None = None,
     user_global_path: Path | str | None = None,
     verbose: bool = False,
+    cwd: Path | None = None,
 ) -> dict[str, Any]:
     """Return the merged settings dict.
 
@@ -65,10 +132,16 @@ def load_agent_settings(
     ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
     ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
     user-global that are not on the whitelist.
+
+    ``cwd`` enables the in-project cascade: when provided **and**
+    ``find_project_root(cwd)`` reaches a ``.git`` ancestor, the loader
+    walks every ``.agent-settings.yml`` from the repo root down to
+    ``cwd`` and merges them shallowest → deepest (deepest wins).
+    Non-root layers are **not** whitelist-filtered (they live inside the
+    project boundary). When ``cwd`` is ``None`` (default), the loader
+    falls back to the single ``project_path`` behaviour — back-compat
+    with pre-cascade callers.
     """
-    project = _read_yaml(
-        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
-    ) or {}
     user_global_raw = _read_yaml(
         Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
     ) or {}
@@ -82,12 +155,48 @@ def load_agent_settings(
             sorted(ignored),
         )
 
+    cascade = _resolve_cascade_paths(cwd, project_path)
+
     merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
     _deep_merge(merged, user_global_filtered)
-    _deep_merge(merged, project)
+    for path in cascade:
+        layer = _read_yaml(path) or {}
+        if layer:
+            _deep_merge(merged, layer)
     return merged
 
 
+def iter_setting_overrides(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    cwd: Path | None = None,
+) -> Iterator[tuple[str, Any, Path]]:
+    """Yield ``(dotted_key, value, source_path)`` for every leaf setting.
+
+    Walks the same cascade as :func:`load_agent_settings` and emits one
+    tuple per leaf observed at each layer (user-global → repo-root →
+    intermediates → CWD). Callers can detect overrides by grouping
+    tuples on ``dotted_key`` — the deepest tuple per group wins. Useful
+    for ``task settings:trace`` and other banner-only diagnostics.
+    Never blocks, never raises on missing files.
+    """
+    user_global_path_resolved = (
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+    )
+    user_global_raw = _read_yaml(user_global_path_resolved) or {}
+    user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)
+    if user_global_filtered:
+        for key in _leaf_paths(user_global_filtered):
+            yield key, _get_dotted(user_global_filtered, key), user_global_path_resolved
+
+    for path in _resolve_cascade_paths(cwd, project_path):
+        layer = _read_yaml(path)
+        if not layer:
+            continue
+        for key in _leaf_paths(layer):
+            yield key, _get_dotted(layer, key), path
+
+
 def _read_yaml(path: Path) -> dict[str, Any] | None:
     """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
     if not path.is_file():

package/scripts/_lib/agents_overlay.py

@@ -0,0 +1,109 @@
+"""Resolve files under ``agents/<kind>/<name>.md`` via the cascade.
+
+Phase 1 of road-to-portable-runtime-and-update-check. Companion to
+``agent_settings.py``: where the settings loader merges YAML, this
+resolves single-file overlays — overrides, contexts, decisions — to a
+single deepest match across the in-project ancestor chain plus the
+user-global directory (when the ``kind`` is whitelisted).
+
+Resolution order (deepest wins, every layer optional):
+
+  N. ``~/.config/agent-config/agents/<kind>/<name>.md``  (user-global; weakest;
+                                                          ``kind`` must be in
+                                                          ``USER_GLOBAL_OVERLAY_KINDS``)
+N-1. ``<repo-root>/agents/<kind>/<name>.md``
+N-2. ``<intermediate-dir>/agents/<kind>/<name>.md``      (optional)
+  1. ``<CWD>/agents/<kind>/<name>.md``                   (deepest, wins)
+
+Asymmetry: ``overrides/`` is the developer's personal layer and may
+live user-global; ``contexts/`` and ``decisions/`` are project-shaped
+and must not leak across projects, so the user-global layer is
+silently skipped for them. Stateful subdirs (``state/``, ``memory/``,
+``roadmaps/``, ``work_engine/``, ``council-*/``) are not cascade-eligible
+at all and raise ``ValueError`` when passed as ``kind``.
+
+Contract — pure, read-only, tolerant:
+
+* Does not read file contents — returns the resolved ``Path`` only.
+* Missing layer / missing file → silently skipped, never raises.
+* Invalid ``kind`` → ``ValueError`` (programmer error, not user input).
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from scripts._lib.agent_settings import find_project_root
+
+logger = logging.getLogger(__name__)
+
+#: Subdirs of ``agents/`` that participate in the cascade. Every entry
+#: is **additive** (single-file artefacts; deepest wins). Stateful or
+#: session-scoped subdirs (``state/``, ``memory/``, ``roadmaps/``,
+#: ``work_engine/``, ``.agent-prices.md``, ``council-*/``) are
+#: deliberately excluded — they are project-rooted only.
+CASCADE_ELIGIBLE_KINDS: frozenset[str] = frozenset({
+    "overrides",
+    "contexts",
+    "decisions",
+})
+
+#: Subset of :data:`CASCADE_ELIGIBLE_KINDS` allowed to live at the
+#: user-global layer (``~/.config/agent-config/agents/<kind>/``).
+#: ``contexts/`` and ``decisions/`` are project-shaped and must not leak
+#: across projects; only ``overrides/`` — the developer's personal
+#: layer — is whitelisted.
+USER_GLOBAL_OVERLAY_KINDS: frozenset[str] = frozenset({"overrides"})
+
+USER_GLOBAL_AGENTS_DIR = Path.home() / ".config" / "agent-config" / "agents"
+
+
+def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
+    """Return the deepest existing ``agents/<kind>/<name>.md`` or ``None``.
+
+    Walks the in-project ancestor chain from ``cwd`` to the ``.git``
+    repo root (inclusive) and probes each layer for
+    ``agents/<kind>/<name>.md``. Falls through to the user-global
+    directory only when ``kind in USER_GLOBAL_OVERLAY_KINDS``. Returns
+    the **deepest** existing file (highest precedence), or ``None`` if
+    no layer carries the overlay.
+
+    ``name`` is treated as a basename — no path traversal, no
+    subdirectories. Callers that need nested layouts should encode the
+    structure inside the overlay file, not the filename.
+    """
+    if kind not in CASCADE_ELIGIBLE_KINDS:
+        raise ValueError(
+            f"agents_overlay: kind {kind!r} not cascade-eligible "
+            f"(allowed: {sorted(CASCADE_ELIGIBLE_KINDS)})",
+        )
+
+    # Candidate layers, shallowest → deepest. Last match wins.
+    candidates: list[Path] = []
+
+    if kind in USER_GLOBAL_OVERLAY_KINDS:
+        candidates.append(USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
+
+    root = find_project_root(cwd)
+    if root is not None:
+        cwd_resolved = cwd.resolve()
+        chain: list[Path] = []
+        cursor = cwd_resolved
+        while True:
+            chain.append(cursor)
+            if cursor == root:
+                break
+            parent = cursor.parent
+            if parent == cursor:
+                break
+            cursor = parent
+        chain.reverse()
+        for layer_dir in chain:
+            candidates.append(layer_dir / "agents" / kind / f"{name}.md")
+
+    deepest: Path | None = None
+    for candidate in candidates:
+        if candidate.is_file():
+            deepest = candidate
+    return deepest

package/scripts/_lib/pin_resolver.py

@@ -0,0 +1,152 @@
+"""Pin-aware version resolver for the ``agent-config`` dispatcher.
+
+Phase 3 of road-to-portable-runtime-and-update-check (P3.2). The
+dispatcher consults this module **before** doing any work. If
+``.agent-settings.yml`` carries a non-empty ``agent_config_version``
+pin and the currently running package version does not match, the
+process re-execs via ``npx @event4u/agent-config@<pin> <argv>``.
+
+Determinism is the goal: a consumer's ``npx`` cache may resolve to a
+different version than the project pinned to, and the resolver
+guarantees the pinned version is the one that actually runs.
+
+Escape hatch: ``AGENT_CONFIG_NO_PIN_REEXEC=1`` disables the re-exec
+entirely (used for local development of the package itself and for
+the recursion guard described below).
+
+Recursion guard: the parent sets ``AGENT_CONFIG_PIN_REEXEC_DEPTH=1``
+on the child env so the re-exec'd child does not loop if the freshly
+spawned ``npx`` resolves to a still-mismatched version. One re-exec
+per process, full stop.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+
+PACKAGE_NAME = "@event4u/agent-config"
+PIN_KEY = "agent_config_version"
+NO_REEXEC_ENV = "AGENT_CONFIG_NO_PIN_REEXEC"
+REEXEC_DEPTH_ENV = "AGENT_CONFIG_PIN_REEXEC_DEPTH"
+
+
+def _normalize(version: str) -> str:
+    return version.strip().lstrip("v")
+
+
+def read_pin(cwd: Path, *, settings_loader=None) -> Optional[str]:
+    """Return the pinned version from the cascaded settings, or ``None``.
+
+    Empty string and missing key both yield ``None``.
+    """
+    if settings_loader is None:
+        from scripts._lib import agent_settings  # local import (test override)
+
+        settings_loader = agent_settings.load_agent_settings
+
+    try:
+        settings = settings_loader(cwd=cwd)
+    except Exception:
+        return None
+    raw = settings.get(PIN_KEY)
+    if not isinstance(raw, str):
+        return None
+    pin = raw.strip()
+    return pin or None
+
+
+def should_reexec(
+    pin: Optional[str],
+    installed: str,
+    *,
+    env: Optional[dict] = None,
+) -> bool:
+    """Pure predicate: do we need to re-exec under the pinned version?"""
+    env = env if env is not None else os.environ
+    if env.get(NO_REEXEC_ENV) == "1":
+        return False
+    if env.get(REEXEC_DEPTH_ENV) == "1":
+        return False
+    if not pin:
+        return False
+    if not installed:
+        return False
+    return _normalize(pin) != _normalize(installed)
+
+
+def build_reexec_argv(pin: str, argv: list[str]) -> list[str]:
+    """Build the ``npx`` argv that re-execs at the pinned version."""
+    return ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(pin)}", *argv]
+
+
+def maybe_reexec(
+    installed: str,
+    *,
+    cwd: Optional[Path] = None,
+    argv: Optional[list[str]] = None,
+    env: Optional[dict] = None,
+    runner=None,
+) -> Optional[int]:
+    """Re-exec at the pinned version if needed; return the child exit code.
+
+    Returns ``None`` when no re-exec is performed (caller continues).
+    The injected ``runner`` covers the test path — defaults to
+    :func:`os.execvpe` on real invocations.
+    """
+    cwd = cwd or Path.cwd()
+    argv = argv if argv is not None else sys.argv
+    env = env if env is not None else os.environ
+
+    pin = read_pin(cwd)
+    if not should_reexec(pin, installed, env=env):
+        return None
+
+    assert pin is not None  # narrowed by should_reexec
+    npx = shutil.which("npx")
+    if not npx:
+        # Cannot re-exec without npx — silently fall back to running
+        # the locally-installed version. Better to do something than
+        # to die because of a missing CLI.
+        return None
+
+    new_argv = build_reexec_argv(pin, argv[1:] if argv else [])
+    child_env = dict(env)
+    child_env[REEXEC_DEPTH_ENV] = "1"
+
+    if runner is None:
+        # Replace the current process; never returns on success.
+        os.execvpe(npx, new_argv, child_env)
+        return 1  # unreachable on POSIX
+    return runner(npx, new_argv, child_env)
+
+
+def _parse_cli(argv: list[str]) -> tuple[Path, str, list[str]]:
+    """Parse the dispatcher-facing argv: ``--cwd X --installed Y -- ARGS``."""
+    cwd = Path.cwd()
+    installed = ""
+    forward: list[str] = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token == "--cwd" and i + 1 < len(argv):
+            cwd = Path(argv[i + 1])
+            i += 2
+        elif token == "--installed" and i + 1 < len(argv):
+            installed = argv[i + 1]
+            i += 2
+        elif token == "--":
+            forward = argv[i + 1:]
+            break
+        else:
+            i += 1
+    return cwd, installed, forward
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cwd, installed, forward = _parse_cli(sys.argv[1:])
+    # Build the argv the child should see: ``agent-config <forward...>``.
+    child_argv = ["agent-config", *forward]
+    maybe_reexec(installed, cwd=cwd, argv=child_argv)

package/scripts/_lib/update_check.py

@@ -0,0 +1,183 @@
+"""Daily update-check banner for the ``agent-config`` dispatcher.
+
+Phase 2 of road-to-portable-runtime-and-update-check. Pure functions:
+``check_for_update()`` decides whether a banner should be emitted and
+returns the banner string (or ``None``). The dispatcher prints the
+returned string to ``stderr`` after the subcommand finishes — never
+delaying the work, never prompting.
+
+Design constraints (see roadmap P2):
+
+- Stdlib only (no new deps); the package's Python floor is stdlib-only.
+- 1 s hard timeout on the registry call; network failure is silent.
+- 24 h cadence gated by ``~/.config/agent-config/update-check.json``.
+- Suppress in CI, on non-TTY stdout, when ``AGENT_CONFIG_NO_UPDATE_CHECK=1``,
+  or when ``update_check.enabled: false`` in settings.
+- State file mode is ``0600``.
+
+The dispatcher is the only call site. Tests mock ``now``, the state
+path, and ``fetch_latest_from_npm`` to cover every branch.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+PACKAGE_NAME = "@event4u/agent-config"
+NPM_REGISTRY_URL = f"https://registry.npmjs.org/{PACKAGE_NAME}/latest"
+FETCH_TIMEOUT_S = 1.0
+CHECK_WINDOW = timedelta(hours=24)
+
+DEFAULT_STATE_PATH = Path.home() / ".config" / "agent-config" / "update-check.json"
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def fetch_latest_from_npm(
+    *,
+    timeout: float = FETCH_TIMEOUT_S,
+    url: str = NPM_REGISTRY_URL,
+) -> Optional[str]:
+    """Return the ``latest`` dist-tag version, or ``None`` on any failure.
+
+    Hard 1 s timeout. Any exception (network, JSON, missing key) yields
+    ``None`` — the update check is best-effort.
+    """
+    try:
+        req = urllib.request.Request(
+            url,
+            headers={"Accept": "application/json", "User-Agent": "agent-config-update-check"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 — fixed URL
+            payload = json.load(resp)
+        version = payload.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (urllib.error.URLError, TimeoutError, ValueError, OSError, json.JSONDecodeError):
+        return None
+    return None
+
+
+def _read_state(path: Path) -> dict:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        if isinstance(data, dict):
+            return data
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def _write_state(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".update-check-", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, sort_keys=True)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _should_check(state: dict, now: datetime) -> bool:
+    last = state.get("last_check_utc")
+    if not isinstance(last, str):
+        return True
+    try:
+        last_dt = datetime.fromisoformat(last.replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    if last_dt.tzinfo is None:
+        last_dt = last_dt.replace(tzinfo=timezone.utc)
+    return (now - last_dt) >= CHECK_WINDOW
+
+
+def _format_banner(latest: str, installed: str) -> str:
+    return (
+        f"ℹ️  agent-config {latest} available (you have {installed}).\n"
+        f"    Update: npx {PACKAGE_NAME} update"
+    )
+
+
+def _is_newer(latest: str, installed: str) -> bool:
+    def _parse(v: str) -> tuple:
+        parts = v.lstrip("v").split("-", 1)[0].split(".")
+        out = []
+        for p in parts[:3]:
+            try:
+                out.append(int(p))
+            except ValueError:
+                out.append(0)
+        while len(out) < 3:
+            out.append(0)
+        return tuple(out)
+
+    return _parse(latest) > _parse(installed)
+
+
+def check_for_update(
+    installed_version: str,
+    *,
+    now: Optional[datetime] = None,
+    state_path: Optional[Path] = None,
+    env: Optional[dict] = None,
+    is_tty: Optional[bool] = None,
+    settings_enabled: bool = True,
+    fetcher=fetch_latest_from_npm,
+) -> Optional[str]:
+    """Decide whether to show an update banner. Pure (modulo state file).
+
+    Returns the banner string or ``None``. ``None`` covers every
+    suppression branch (CI, non-TTY, opt-out, within 24 h, network
+    failure, no update available).
+    """
+    env = env if env is not None else os.environ
+    if env.get("AGENT_CONFIG_NO_UPDATE_CHECK") == "1":
+        return None
+    if env.get("CI") in {"1", "true"} or env.get("GITHUB_ACTIONS") == "true":
+        return None
+    if not settings_enabled:
+        return None
+    if is_tty is None:
+        is_tty = sys.stdout.isatty()
+    if not is_tty:
+        return None
+
+    now = now or _now_utc()
+    state_path = state_path or DEFAULT_STATE_PATH
+    state = _read_state(state_path)
+    if not _should_check(state, now):
+        latest = state.get("last_seen_version")
+        if isinstance(latest, str) and _is_newer(latest, installed_version):
+            return _format_banner(latest, installed_version)
+        return None
+
+    latest = fetcher()
+    payload = {
+        "last_check_utc": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "last_seen_version": latest or state.get("last_seen_version", ""),
+        "installed_version": installed_version,
+    }
+    try:
+        _write_state(state_path, payload)
+    except OSError:
+        pass
+
+    if not latest or not _is_newer(latest, installed_version):
+        return None
+    return _format_banner(latest, installed_version)