@event4u/agent-config 1.40.0 → 1.41.1

package/docs/setup/per-ide/claude-desktop.md

@@ -68,9 +68,15 @@ If the menu is empty:
 
 ## Step 3 — optional MCP server
 
-Claude Desktop also speaks MCP. Wiring up the hosted `agent-config-mcp`
-Worker exposes the **full** skill / rule / command catalog (~480 items)
-on demand, on top of the 15 you installed in Step 1.
+Claude Desktop also speaks MCP. Wiring up your own self-hosted
+`agent-config-mcp` Cloudflare Worker exposes the **full** skill / rule /
+command catalog (~480 items) on demand, on top of the 15 you installed
+in Step 1.
+
+Deploy the Worker first per [`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) — your
+URL will be `https://agent-config-mcp.<your-account>.workers.dev`
+(or a custom domain you wire up in Step 7). Replace
+`https://your-worker.workers.dev` below with that URL.
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
 (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows /
@@ -81,7 +87,25 @@ Linux is `~/.config/Claude/claude_desktop_config.json`):
   "mcpServers": {
     "agent-config": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
+    }
+  }
+}
+```
+
+If you set the `MCP-Token` secret on the Worker (recommended — see
+[`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) § Bearer auth), add the header:
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
@@ -89,11 +113,12 @@ Linux is `~/.config/Claude/claude_desktop_config.json`):
 
 A pre-wired template ships at
 [`templates/claude_desktop_config.json.template`](../../../templates/claude_desktop_config.json.template) —
-copy + uncomment the MCP block.
+copy, swap the placeholder URL for your deploy, and uncomment the MCP
+block.
 
 Restart Claude Desktop. The 🔌 icon shows the connector under
 **Settings → Connectors**. Full transport details (mcp-remote vs.
-native HTTP) live in
+native HTTP) and per-client Bearer-auth snippets live in
 [`../mcp-client-config.md`](../mcp-client-config.md).
 
 ## Claude Desktop ↔ Claude Code config sharing
@@ -125,7 +150,7 @@ Desktop config**. Once Step 1 + Step 3 are done in Desktop:
   inside Cowork sessions without a separate install.
 - Cowork-specific limit (per Anthropic docs): MCP tools that write to
   the local filesystem are sandboxed — read-only tools (the entire
-  hosted `agent-config-mcp` surface) work fine.
+  `agent-config-mcp` Worker surface) work fine.
 
 If a feature works in Desktop but not in Cowork, check that you're on
 a paid plan — Cowork is gated, Desktop's free tier has the full

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.40.0",
+    "version": "1.41.1",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_lib/script_output.py

@@ -43,20 +43,24 @@ def _read_settings_level(settings_path: Path) -> str | None:
     """Read verbosity.script_output from .agent-settings.yml.
 
     Returns None when the file is missing, PyYAML is unavailable, or
-    the key is absent. Errors fall through to the default level.
+    the key is absent. Errors fall through to the default level. Goes
+    through the centralized loader (road-to-portable-dev-preferences P3)
+    so the tolerance contract — missing file, malformed YAML, no PyYAML
+    — degrades uniformly across scripts. ``verbosity.script_output`` is
+    not on the user-global whitelist, so a value there is silently
+    ignored; the project file is the only source for this knob.
     """
-    if not settings_path.is_file():
-        return None
+    # Lazy import — supports both `python3 scripts/foo.py` (sys.path
+    # contains scripts/) and `pytest` (scripts._lib is a proper package).
     try:
-        import yaml  # type: ignore[import-untyped]
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]  # noqa: PLC0415
     except ImportError:
-        return None
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    section = data.get("verbosity") if isinstance(data, dict) else None
+        from scripts._lib.agent_settings import (  # noqa: PLC0415
+            load_agent_settings,
+        )
+
+    data = load_agent_settings(project_path=settings_path)
+    section = data.get("verbosity")
     if not isinstance(section, dict):
         return None
     value = section.get("script_output")

package/scripts/ai_council/session.py

@@ -88,15 +88,21 @@ def _load_retention_days(settings_path: Path | None = None) -> int:
     file, invalid YAML, missing key, non-int value). Pruning never
     blocks the council on a settings error.
     """
-    path = settings_path or SETTINGS_FILE
-    if not path.exists():
-        return DEFAULT_RETENTION_DAYS
+    # Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    # contract handles missing file / malformed YAML / no PyYAML uniformly.
+    # ``ai_council.session_retention_days`` is not whitelisted, so the
+    # user-global file cannot override the project value.
     try:
-        import yaml  # type: ignore[import-not-found]
-        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-    except Exception:  # noqa: BLE001 - never block on settings parse
-        return DEFAULT_RETENTION_DAYS
-    ai = data.get("ai_council") if isinstance(data, dict) else None
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    path = settings_path or SETTINGS_FILE
+    data = load_agent_settings(project_path=path)
+    ai = data.get("ai_council")
     if not isinstance(ai, dict):
         return DEFAULT_RETENTION_DAYS
     raw = ai.get("session_retention_days", DEFAULT_RETENTION_DAYS)

package/scripts/chat_history.py

@@ -609,27 +609,36 @@ def status(*, path: Path | None = None) -> dict[str, Any]:
     }
 
 
+def _load_chat_history_section(settings_path: Path) -> dict | None:
+    """Return the ``chat_history`` mapping from .agent-settings.yml or None.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    No ``chat_history.*`` keys are whitelisted, so user-global cannot
+    leak into this section — the project file remains authoritative.
+    """
+    try:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=settings_path)
+    section = data.get("chat_history")
+    return section if isinstance(section, dict) else None
+
+
 def _read_chat_history_enabled(settings_path: Path) -> bool:
     """Read chat_history.enabled from .agent-settings.yml.
 
     Returns False when the file is missing, malformed, lacks the
     `chat_history` section, or sets enabled to false. Default-deny so
     `turn-check` is safe to run from projects that have not opted in.
-    PyYAML is imported lazily — the rest of this module works without it.
     """
-    if not settings_path.is_file():
-        return False
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return True  # fail open: settings file present but no parser
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return False
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return False
     return bool(section.get("enabled", False))
 
@@ -739,19 +748,8 @@ VALID_PLATFORMS = tuple(PLATFORM_EVENT_MAP.keys())
 
 def _read_chat_history_frequency(settings_path: Path) -> str:
     """Read chat_history.frequency from .agent-settings.yml. Default per_phase."""
-    if not settings_path.is_file():
-        return "per_phase"
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return "per_phase"
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return "per_phase"
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return "per_phase"
     val = str(section.get("frequency", "per_phase")).lower()
     return val if val in VALID_FREQS else "per_phase"
@@ -764,19 +762,8 @@ def _read_chat_history_max_sessions(settings_path: Path) -> int:
     Used by ``prune_sessions`` to decide how many distinct ``s`` tags
     survive in the body.
     """
-    if not settings_path.is_file():
-        return DEFAULT_MAX_SESSIONS
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return DEFAULT_MAX_SESSIONS
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return DEFAULT_MAX_SESSIONS
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return DEFAULT_MAX_SESSIONS
     try:
         n = int(section.get("max_sessions", DEFAULT_MAX_SESSIONS))
@@ -794,19 +781,8 @@ def _read_text_limits(settings_path: Path) -> dict[str, int]:
     values are clamped to 0. Non-int values are silently dropped.
     """
     out = dict(DEFAULT_TEXT_LIMITS)
-    if not settings_path.is_file():
-        return out
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return out
-    try:
-        with settings_path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return out
-    section = data.get("chat_history") if isinstance(data, dict) else None
-    if not isinstance(section, dict):
+    section = _load_chat_history_section(settings_path)
+    if section is None:
         return out
     overrides = section.get("text_limits")
     if not isinstance(overrides, dict):

package/scripts/command_suggester/settings.py

@@ -42,20 +42,22 @@ def load_settings(settings_path: Path | str | None = None) -> Settings:
 
 
 def _read_section(path: Path) -> dict[str, Any] | None:
-    """Return the ``commands.suggestion`` mapping or ``None`` on any miss."""
-    if not path.is_file():
-        return None
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return None
+    """Return the ``commands.suggestion`` mapping or ``None`` on any miss.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    No ``commands.*`` keys are whitelisted, so user-global cannot cascade
+    into this section.
+    """
     try:
-        with path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    if not isinstance(data, dict):
-        return None
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=path)
     commands = data.get("commands")
     if not isinstance(commands, dict):
         return None

package/scripts/compile_router.py

@@ -100,16 +100,20 @@ def _normalize_trigger(item) -> dict | None:
 
 
 def _load_settings() -> dict:
-    """Read .agent-settings.yml for compile-time toggles. Stdlib-only fallback."""
-    if not SETTINGS_PATH.exists():
-        return {}
-    text = SETTINGS_PATH.read_text(encoding="utf-8")
+    """Read .agent-settings.yml for compile-time toggles.
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
+    """
     try:
-        import yaml  # type: ignore
-        data = yaml.safe_load(text) or {}
-        return data if isinstance(data, dict) else {}
-    except ImportError:
-        return {}
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    return load_agent_settings(project_path=SETTINGS_PATH)
 
 
 def _collect(rules_dir: Path) -> dict:

package/scripts/compress.py

@@ -46,28 +46,31 @@ def _read_augment_rules_use_symlinks() -> bool:
     """Read augment.rules_use_symlinks from .agent-settings.yml.
 
     Returns True only when the setting is present under the top-level
-    ``augment:`` block and resolves to a truthy YAML scalar
-    (true/yes/on/1, case-insensitive). Missing file, missing block, or
-    any other value → False (preserve copy default).
+    ``augment:`` block and resolves to a truthy value. Missing file,
+    missing block, or any other value → False (preserve copy default).
+
+    Centralized loader (road-to-portable-dev-preferences P3): tolerance
+    contract handles missing file / malformed YAML / no PyYAML uniformly.
     """
-    if not SETTINGS_FILE.exists():
-        return False
     try:
-        text = SETTINGS_FILE.read_text(encoding="utf-8")
-    except OSError:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+
+    data = load_agent_settings(project_path=SETTINGS_FILE)
+    augment = data.get("augment")
+    if not isinstance(augment, dict):
         return False
-    in_augment = False
-    for line in text.splitlines():
-        stripped = line.lstrip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if not line.startswith((" ", "\t")):
-            in_augment = stripped.startswith("augment:")
-            continue
-        if in_augment:
-            m = re.match(r"^\s+rules_use_symlinks\s*:\s*([^\s#]+)", line)
-            if m:
-                return m.group(1).strip().lower() in ("true", "yes", "on", "1")
+    value = augment.get("rules_use_symlinks")
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "yes", "on", "1")
+    if isinstance(value, int):
+        return value == 1
     return False
 
 

package/scripts/council_cli.py

@@ -53,9 +53,15 @@ class CouncilDisabledError(RuntimeError):
 
 
 def load_settings(path: Path = SETTINGS_FILE) -> dict[str, Any]:
-    if not path.exists():
-        return {}
-    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    """Load merged settings via the centralized loader.
+
+    road-to-portable-dev-preferences P3 migration: tolerance contract
+    (missing file / malformed YAML / no PyYAML) is handled uniformly by
+    ``load_agent_settings``. ``ai_council.*`` keys are not whitelisted,
+    so the project file remains authoritative for council config.
+    """
+    from scripts._lib.agent_settings import load_agent_settings
+    return load_agent_settings(project_path=path)
 
 
 def build_members(

package/scripts/mcp_parity_smoke.py

@@ -29,8 +29,10 @@ from typing import Any
 _SCRIPTS = Path(__file__).resolve().parent
 sys.path.insert(0, str(_SCRIPTS))
 
+from mcp_server.catalog import load_catalog  # noqa: E402
 from mcp_server.prompts import load_all_prompts, to_mcp_prompt_meta  # noqa: E402
 from mcp_server.resources import load_all_resources, to_mcp_resource_meta  # noqa: E402
+from mcp_server.tools import ALLOWLIST  # noqa: E402
 
 PAGE_SIZE = 50
 
@@ -96,6 +98,21 @@ def _normalize_resources(payload: dict[str, Any]) -> list[dict[str, Any]]:
     return sorted(out, key=lambda x: x["uri"])
 
 
+def _local_tools_list() -> dict[str, Any]:
+    """Tools catalog + allowlist as the stdio server publishes them."""
+    catalog_names = [c.name for c in load_catalog()]
+    allowlist_names = list(ALLOWLIST.keys())
+    return {"tools": [{"name": n} for n in sorted(set(catalog_names + allowlist_names))]}
+
+
+def _normalize_tools(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    """Compare on `name` only — descriptions / schemas drift acceptably."""
+    return sorted(
+        [{"name": t["name"]} for t in payload.get("tools", [])],
+        key=lambda x: x["name"],
+    )
+
+
 def _diff(label: str, local: list[Any], remote: list[Any]) -> int:
     if local == remote:
         print(f"✅  {label}: {len(local)} entries match")
@@ -129,8 +146,9 @@ def main() -> int:
     failed += _diff("resources/list", local_r, remote_r)
 
     try:
-        _ = _rpc(args.target, "tools/list")
-        print("✅  tools/list: round-trips (stub list — content not parity-checked)")
+        local_t = _normalize_tools(_local_tools_list())
+        remote_t = _normalize_tools(_rpc(args.target, "tools/list"))
+        failed += _diff("tools/list", local_t, remote_t)
     except Exception as e:
         print(f"❌  tools/list: {e}")
         failed += 1

package/scripts/mcp_server/catalog.py

@@ -0,0 +1,125 @@
+"""Consumer tool catalog — source of truth for Phase 1 discovery stubs.
+
+Loaded once at module import from ``consumer_tool_catalog.json``. Both
+the stdio server (``tools.py``) and the cloud pack
+(``scripts/pack_mcp_content.py``) read from this file so the manifest
+returned by ``tools/list`` on either transport is byte-identical apart
+from per-tool ``implemented_on`` metadata.
+
+Side-effect classification (``ro`` / ``fs-write`` / ``shell``) and the
+``not_implemented`` envelope contract live in
+``docs/contracts/mcp-tool-stub-envelope.md``.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_CATALOG_FILE = Path(__file__).resolve().parent / "consumer_tool_catalog.json"
+
+# Stable error code surfaced in the ``not_implemented`` envelope. The
+# Worker mirrors this string verbatim — keep them in sync via the
+# envelope contract.
+NOT_IMPLEMENTED_CODE = "not_implemented"
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    """One row in ``consumer_tool_catalog.json``.
+
+    ``implemented_on`` lists transports where a real handler is wired
+    (``stdio`` / ``worker``); missing transports return the
+    ``not_implemented`` envelope.
+    """
+
+    name: str
+    description: str
+    side_effect: str
+    implemented_on: tuple[str, ...]
+    input_schema: dict[str, Any]
+
+
+def _validate(raw: dict[str, Any]) -> None:
+    """Refuse to boot on a malformed catalog. Boot-time errors only."""
+    if raw.get("schema_version") != 1:
+        raise ValueError(
+            f"catalog: unsupported schema_version="
+            f"{raw.get('schema_version')!r}; expected 1"
+        )
+    tools = raw.get("tools")
+    if not isinstance(tools, list) or not tools:
+        raise ValueError("catalog: 'tools' must be a non-empty list")
+    seen: set[str] = set()
+    for entry in tools:
+        if not isinstance(entry, dict):
+            raise ValueError("catalog: every tool entry must be an object")
+        for field in ("name", "description", "side_effect", "input_schema"):
+            if field not in entry:
+                raise ValueError(f"catalog: tool missing '{field}'")
+        if entry["side_effect"] not in ("ro", "fs-write", "shell"):
+            raise ValueError(
+                f"catalog: tool {entry['name']!r} has invalid side_effect "
+                f"{entry['side_effect']!r} (expected ro / fs-write / shell)"
+            )
+        name = entry["name"]
+        if name in seen:
+            raise ValueError(f"catalog: duplicate tool name {name!r}")
+        seen.add(name)
+
+
+def load_catalog(path: Path | None = None) -> list[CatalogEntry]:
+    """Parse and validate the catalog. Returns entries in file order."""
+    target = path or _CATALOG_FILE
+    raw = json.loads(target.read_text(encoding="utf-8"))
+    _validate(raw)
+    return [
+        CatalogEntry(
+            name=t["name"],
+            description=t["description"],
+            side_effect=t["side_effect"],
+            implemented_on=tuple(t.get("implemented_on") or ()),
+            input_schema=t["input_schema"],
+        )
+        for t in raw["tools"]
+    ]
+
+
+def load_raw(path: Path | None = None) -> dict[str, Any]:
+    """Return the raw parsed JSON. Used by the cloud packer."""
+    target = path or _CATALOG_FILE
+    raw = json.loads(target.read_text(encoding="utf-8"))
+    _validate(raw)
+    return raw
+
+
+def install_hint(raw: dict[str, Any] | None = None) -> str:
+    """Stable install-hint surfaced in the envelope."""
+    data = raw if raw is not None else load_raw()
+    return str(data.get("install_hint_stdio") or "")
+
+
+def not_implemented_envelope(
+    tool_name: str,
+    *,
+    transport: str,
+    install_hint_value: str,
+) -> dict[str, Any]:
+    """Wire-shape error envelope used when a stub is invoked.
+
+    Mirrored verbatim by the Cloud Worker (`workers/mcp/src/stubs.ts`).
+    """
+    return {
+        "code": NOT_IMPLEMENTED_CODE,
+        "tool": tool_name,
+        "transport": transport,
+        "install_hint": install_hint_value,
+        "alternative": "stdio",
+        "message": (
+            f"Tool '{tool_name}' is in the discovery catalog but not "
+            f"implemented on the {transport} transport. See the install "
+            "hint to wire it up locally, or check "
+            "docs/contracts/mcp-tool-stub-envelope.md."
+        ),
+    }