@event4u/agent-config 2.12.0 → 2.14.0

package/scripts/ai_council/advisors.py

@@ -0,0 +1,148 @@
+"""Thinking-style advisors — replace-mode call planning (Phase 6).
+
+When `agents/.ai-council.yml` enables an advisor (e.g. `contrarian`
+bound to `member: anthropic`), the orchestrator REPLACES the matching
+plain-member call with an advisor-persona call on the same provider.
+Same total call count as a plain run; bounded extra cost beyond the
+persona-prompt token delta.
+
+This module owns:
+
+- `AdvisorPlan`  — resolved swap for a single provider (persona text,
+  display name, optional model override).
+- `plan_advisor_swap()` — walks the enabled advisors, reads their
+  persona files, and returns the per-provider plan map consumed by
+  `orchestrator.consult()` / `estimate()` and by the CLI.
+- `resolve_persona_text()` — reads a persona file with compressed-tree
+  preference and frontmatter strip.
+
+Cross-validation against the members block already ran at config load
+(`config._build_config`); this module trusts that contract and only
+enforces the **one-advisor-per-provider** rule (replace-mode invariant).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from scripts.ai_council.config import AdvisorConfig, CouncilConfigError
+
+
+@dataclass(frozen=True)
+class AdvisorPlan:
+    """Resolved advisor swap for a single provider."""
+
+    name: str
+    display_name: str
+    member: str
+    persona_text: str
+    model_override: str | None = None
+
+
+_FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+
+
+def _split_frontmatter(raw: str) -> tuple[dict, str]:
+    """Return ``(frontmatter_dict, body)``. Missing frontmatter → ``({}, raw)``."""
+    match = _FRONTMATTER_RE.match(raw)
+    if not match:
+        return {}, raw
+    try:
+        meta = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        meta = {}
+    if not isinstance(meta, dict):
+        meta = {}
+    body = raw[match.end():]
+    return meta, body
+
+
+def _display_name_from(advisor_name: str, frontmatter: dict) -> str:
+    """Prefer frontmatter ``role``; fall back to titleized advisor key."""
+    role = frontmatter.get("role")
+    if isinstance(role, str) and role.strip():
+        return role.strip()
+    return advisor_name.replace("-", " ").replace("_", " ").title()
+
+
+def resolve_persona_text(
+    persona_path: str,
+    repo_root: Path,
+) -> tuple[str, dict]:
+    """Read a persona file, returning ``(body, frontmatter)``.
+
+    Compressed tree (``.agent-src/``) wins so production runs match the
+    same projection the rest of the package consumes. Uncompressed tree
+    (``.agent-src.uncompressed/``) is the fallback for in-repo
+    development before ``task sync`` has projected the file.
+    """
+    candidates = [
+        repo_root / ".agent-src" / persona_path,
+        repo_root / ".agent-src.uncompressed" / persona_path,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            raw = candidate.read_text(encoding="utf-8")
+            meta, body = _split_frontmatter(raw)
+            return body.strip(), meta
+    searched = "\n  - ".join(str(c) for c in candidates)
+    raise CouncilConfigError(
+        f"Persona file not found for advisor (path={persona_path!r}). "
+        f"Searched:\n  - {searched}"
+    )
+
+
+def plan_advisor_swap(
+    advisors: dict[str, AdvisorConfig],
+    repo_root: Path,
+) -> dict[str, AdvisorPlan]:
+    """Return ``{provider_name: AdvisorPlan}`` for every ENABLED advisor.
+
+    Two enabled advisors targeting the same provider is a
+    ``CouncilConfigError`` — replace-mode runs one advisor per provider
+    so the call plan never doubles up by accident.
+    """
+    plans: dict[str, AdvisorPlan] = {}
+    for adv in advisors.values():
+        if not adv.enabled:
+            continue
+        if adv.member in plans:
+            existing = plans[adv.member].name
+            raise CouncilConfigError(
+                f"advisors.{adv.name} and advisors.{existing} both bind "
+                f"member={adv.member!r}; only one advisor per provider "
+                f"per run (replace-mode invariant)."
+            )
+        body, meta = resolve_persona_text(adv.persona, repo_root)
+        plans[adv.member] = AdvisorPlan(
+            name=adv.name,
+            display_name=_display_name_from(adv.name, meta),
+            member=adv.member,
+            persona_text=body,
+            model_override=adv.model,
+        )
+    return plans
+
+
+def build_persona_labels(
+    plans: dict[str, AdvisorPlan],
+    members: list,
+) -> dict[str, str]:
+    """Build the peer-review ``source → display_name`` map.
+
+    ``source`` is the ``provider:model`` string the peer-review
+    pipeline uses for anonymisation; ``members`` is the post-swap
+    member list (model_override already applied), so the model field
+    matches what the response carries.
+    """
+    labels: dict[str, str] = {}
+    for m in members:
+        plan = plans.get(m.name)
+        if plan is None:
+            continue
+        labels[f"{m.name}:{m.model}"] = plan.display_name
+    return labels

package/scripts/ai_council/airgap.py

@@ -0,0 +1,165 @@
+"""Airgap detection for the AI Council installer / first-run (step-9 P11 · U1).
+
+Probes DNS for the three primary council provider hosts with a short
+timeout. If **all** probes fail the environment is treated as airgapped
+and the installer is expected to seed ``defaults.member_mode: api`` (the
+CLI default would otherwise launch ``codex``/``claude``/``gemini``
+binaries that cannot reach their backends).
+
+Why DNS, not HTTP:
+- DNS is cheap (UDP, ~1 packet), HTTP probes are billable surface.
+- A DNS hit is sufficient to disprove airgap; the actual reachability
+  of the host is checked at first use, not here.
+- No auth required, no false negatives from corporate proxies that
+  block HTTPS but allow DNS.
+
+Public surface:
+- ``COUNCIL_PROBE_HOSTS`` — tuple of hosts to probe.
+- ``probe_host(host, timeout)`` — single-host probe, returns bool.
+- ``detect_airgap(*, hosts, timeout, resolver)`` — returns ``True`` iff
+  every host fails. ``resolver`` is injectable for tests.
+- ``airgap_banner()`` — the one-liner the installer prints when airgap
+  is detected.
+"""
+
+from __future__ import annotations
+
+import socket
+from collections.abc import Callable, Iterable
+
+COUNCIL_PROBE_HOSTS: tuple[str, ...] = (
+    "api.anthropic.com",
+    "api.openai.com",
+    "generativelanguage.googleapis.com",
+)
+
+DEFAULT_TIMEOUT_S: float = 1.0
+
+# Banner string the installer prints when airgap is detected. Wording
+# is part of the Phase 11 contract (roadmap step-9 line 147) and is
+# asserted by tests/test_airgap_detection.py.
+AIRGAP_BANNER: str = (
+    "airgapped environment detected — defaulting to mode: api"
+)
+
+
+def airgap_banner() -> str:
+    """Return the canonical airgap banner (step-9 P11)."""
+
+    return AIRGAP_BANNER
+
+
+Resolver = Callable[[str], None]
+
+
+def _default_resolver(host: str) -> None:
+    """Resolve ``host`` via ``socket.getaddrinfo``.
+
+    Raises ``socket.gaierror`` / ``OSError`` on failure. The timeout is
+    enforced by the caller via ``socket.setdefaulttimeout`` because
+    ``getaddrinfo`` itself has no ``timeout=`` kwarg.
+    """
+
+    socket.getaddrinfo(host, None)
+
+
+def probe_host(
+    host: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> bool:
+    """Return ``True`` iff ``host`` resolves within ``timeout``.
+
+    Any DNS / socket error is treated as unreachable. Test code can
+    inject ``resolver`` to simulate reachability without touching the
+    network.
+    """
+
+    resolver = resolver or _default_resolver
+    previous = socket.getdefaulttimeout()
+    try:
+        socket.setdefaulttimeout(timeout)
+        try:
+            resolver(host)
+        except (socket.gaierror, OSError):
+            return False
+        return True
+    finally:
+        socket.setdefaulttimeout(previous)
+
+
+def detect_airgap(
+    *,
+    hosts: Iterable[str] = COUNCIL_PROBE_HOSTS,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> bool:
+    """Return ``True`` iff **every** host in ``hosts`` is unreachable.
+
+    A single reachable host is enough to disprove airgap — CLI members
+    only need one provider to be usable. Empty ``hosts`` is treated as
+    airgap by definition (no providers to reach).
+    """
+
+    hosts_list = list(hosts)
+    if not hosts_list:
+        return True
+    for host in hosts_list:
+        if probe_host(host, timeout=timeout, resolver=resolver):
+            return False
+    return True
+
+
+def recommended_member_mode(
+    *,
+    hosts: Iterable[str] = COUNCIL_PROBE_HOSTS,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> str:
+    """Return ``"api"`` when airgapped, ``"cli"`` otherwise.
+
+    Convenience wrapper for the installer: matches the Phase 8 default
+    of ``cli`` and the Phase 11 airgap override of ``api``.
+    """
+
+    return "api" if detect_airgap(
+        hosts=hosts, timeout=timeout, resolver=resolver,
+    ) else "cli"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry-point: print recommended mode + banner if airgapped.
+
+    Used by the installer / first-run wrappers (step-9 P11): probe
+    the three provider hosts and exit ``0`` with the recommended mode
+    on stdout. When airgapped also emit the banner on stderr so the
+    installer can surface it without parsing stdout.
+    """
+
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(
+        description="Detect airgap state and print recommended member_mode."
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_S,
+        help=f"per-host DNS timeout in seconds (default: {DEFAULT_TIMEOUT_S})",
+    )
+    args = parser.parse_args(argv)
+
+    is_airgapped = detect_airgap(timeout=args.timeout)
+    mode = "api" if is_airgapped else "cli"
+    if is_airgapped:
+        print(AIRGAP_BANNER, file=sys.stderr)
+    print(mode)
+    return 0
+
+
+if __name__ == "__main__":
+    import sys as _sys
+
+    raise SystemExit(main(_sys.argv[1:]))

package/scripts/ai_council/cli_hints.py

@@ -0,0 +1,123 @@
+"""Per-provider CLI install hints for ``mode: cli`` members (step-9 P2).
+
+When ``build_members`` cannot construct a ``mode: cli`` member because
+the binary is missing on PATH, it records a skip entry of shape
+``{"member": <provider>, "reason": "binary_missing", "detail": <msg>}``
+in the caller's ``skipped`` list. This module turns that bookkeeping
+into an actionable pre-flight banner — one line per skipped member —
+so the user sees *which* CLI to install, *where* to get it, and
+*how* to disable the CLI route as a fallback.
+
+The table is intentionally small and stdlib-only (no HTTP fetch, no
+new dependency): provider → ``(binary, docs_url, one_liner_install)``.
+Surfaced by ``scripts/council_cli.py`` in ``cmd_estimate`` / ``cmd_ask``
+/ ``cmd_debate`` immediately after the cost-estimate header so missing
+CLIs are visible BEFORE the cost decision, not buried in stderr.
+
+Closes PR #150 follow-up **C1** (Claude · UX). See
+``agents/roadmaps/step-9-pr150-feedback-hardening.md`` Phase 2.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Mapping
+
+#: Provider → ``(binary, docs_url, one_liner_install)``.
+#:
+#: - ``binary``: executable name the CLI client looks for via
+#:   ``shutil.which``. Matches ``default_binary`` on the
+#:   ``CliClient`` subclass in ``scripts/ai_council/clients.py``.
+#: - ``docs_url``: canonical install page. Stable upstream URL —
+#:   when a vendor renames the page, update here.
+#: - ``one_liner_install``: shortest copy-pasteable install
+#:   command. Plain shell, no curl-pipe-bash. Users with stricter
+#:   policies are expected to follow ``docs_url`` instead.
+#:
+#: Vendor-official transports (anthropic, openai, gemini) ship as
+#: subscription-authed binaries — install once, ``billable=False``.
+#: Community wrappers (xai, perplexity) consume an API key and stay
+#: ``billable=True`` even on the CLI route — the hint links to the
+#: community project so the user knows what they are installing.
+INSTALL_HINTS: dict[str, tuple[str, str, str]] = {
+    "anthropic": (
+        "claude",
+        "https://docs.anthropic.com/en/docs/claude-code/quickstart",
+        "npm install -g @anthropic-ai/claude-code",
+    ),
+    "openai": (
+        "codex",
+        "https://github.com/openai/codex",
+        "npm install -g @openai/codex",
+    ),
+    "gemini": (
+        "gemini",
+        "https://github.com/google-gemini/gemini-cli",
+        "npm install -g @google/gemini-cli",
+    ),
+    "xai": (
+        "grok",
+        "https://github.com/superagent-ai/grok-cli",
+        "npm install -g @superagent-ai/grok-cli",
+    ),
+    "perplexity": (
+        "perplexity",
+        "https://github.com/perplexityai/perplexity-cli",
+        "npm install -g perplexity-cli",
+    ),
+}
+
+
+def hint_for(provider: str) -> tuple[str, str, str] | None:
+    """Return ``(binary, docs_url, one_liner)`` for ``provider``, else ``None``.
+
+    Unknown providers (community additions not yet table-listed) return
+    ``None`` so the caller can fall through to a generic message rather
+    than crashing the pre-flight banner.
+    """
+    return INSTALL_HINTS.get(provider)
+
+
+def format_install_hints(skipped: Iterable[Mapping[str, object]]) -> str:
+    """Render the per-skip pre-flight banner.
+
+    ``skipped`` is the list ``build_members`` populates — each entry
+    carries ``member`` (provider name), ``reason`` (``binary_missing``
+    or future variants), and ``detail`` (the raw ``CliClientError``
+    message). Output shape, one line per entry:
+
+    ::
+
+        council:cli-skip · <provider> · binary not found · install: <one_liner> · docs: <url>
+
+    For providers with no entry in ``INSTALL_HINTS`` (community additions
+    not yet listed), falls back to the raw ``detail`` so the user still
+    sees the failure mode.
+
+    Returns ``""`` when ``skipped`` is empty so callers can write the
+    string unconditionally without a leading blank line.
+
+    Only ``reason == "binary_missing"`` entries get the install line —
+    other reasons (future: ``auth_expired``, ``parse_failed`` during
+    pre-flight probes) reuse the raw detail without an install hint.
+    """
+    lines: list[str] = []
+    for entry in skipped:
+        name = str(entry.get("member", "?"))
+        reason = str(entry.get("reason", ""))
+        detail = str(entry.get("detail", ""))
+        if reason != "binary_missing":
+            lines.append(
+                f"council:cli-skip · {name} · {reason or 'unknown'} · {detail}"
+            )
+            continue
+        hint = hint_for(name)
+        if hint is None:
+            lines.append(
+                f"council:cli-skip · {name} · binary not found · {detail}"
+            )
+            continue
+        _binary, url, one_liner = hint
+        lines.append(
+            f"council:cli-skip · {name} · binary not found · "
+            f"install: {one_liner} · docs: {url}"
+        )
+    return "\n".join(lines)