@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/_cli/explain_last/scrubber.py

@@ -0,0 +1,105 @@
+"""PII / cost-metadata scrubber for the ``explain last`` trace.
+
+The standard project redactor under
+:mod:`scripts.ai_council.redact_low_impact_entry` is a *refusal* gate —
+it returns ``ok=False`` and asks the human to rephrase. The explain
+surface cannot refuse to produce output; the user already executed the
+upstream command and is now asking *why*. So this module mirrors the
+same regex patterns but performs in-place masking instead of refusal.
+
+Masks applied (resolution order):
+
+1. Raw-key secret prefixes (``sk_live_…``, ``ghp_…`` etc.) and inline
+   ``api_key=…`` shapes → ``<secret>``.
+2. Emails → ``<email>``.
+3. Absolute file paths (``/Users/…``, ``/home/…``, ``C:\\…``) →
+   ``<path>``.
+4. URLs → ``<scheme>://<host>/…`` (path / query / fragment stripped).
+5. ``*.internal`` / ``*.local`` hostnames → ``<host>``.
+6. Monetary amounts (``$1,234``, ``USD 500``) → ``<money>`` — strips
+   billing-cost leakage from council token-usage metadata.
+7. Long strings (> 200 chars) → ``<NNN chars>`` summary.
+
+Limits mirror the AI-Council privacy floor at
+``.augment/rules/low-impact-corpus-privacy-floor.md`` and the regex
+sources at :mod:`scripts.ai_council.redact_low_impact_entry` so behaviour
+stays in lockstep when that floor evolves.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+LONG_STRING_THRESHOLD = 200
+
+_RAW_KEY_PREFIXES = (
+    "sk_live_", "sk_test_", "ghp_", "github_pat_", "gho_", "ghs_",
+    "ghu_", "xoxb-", "xoxp-", "AIza", "AKIA",
+)
+_RAW_KEY_RE = re.compile(
+    "(?:" + "|".join(re.escape(p) for p in _RAW_KEY_PREFIXES) + r")[A-Za-z0-9_\-]{6,}",
+)
+_API_KEY_RE = re.compile(
+    r"(?i)\bapi[_-]?key\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{12,}",
+)
+_EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
+_PATH_RE = re.compile(
+    r"(?:/Users/|/home/|/opt/|/private/|[A-Z]:\\)[\w.\-/\\]+",
+)
+_URL_RE = re.compile(
+    r"\b(?P<scheme>https?|ftp|ws|wss)://(?P<host>[^\s/:?#]+)(?:[^\s]*)?",
+)
+_INTERNAL_HOST_RE = re.compile(
+    r"\b[a-zA-Z0-9][\w.-]*\.(?:internal|local)\b",
+    re.IGNORECASE,
+)
+_MONEY_RE = re.compile(
+    r"(?:[\$€£¥]\s?\d{1,3}(?:[,.]\d{3})*(?:\.\d+)?"
+    r"|\b(?:USD|EUR|GBP|JPY)\s?\d+(?:[,.]\d+)?)",
+)
+
+
+def _strip_url(match: re.Match[str]) -> str:
+    return f"{match.group('scheme')}://{match.group('host')}/…"
+
+
+def scrub_string(value: str) -> str:
+    """Mask every forbidden pattern in ``value`` and return the result.
+
+    Idempotent — running the scrubber twice yields the same string.
+    Order matters: secrets fire first because their substrings overlap
+    with paths and URLs; URLs come before the generic ``<path>`` sweep
+    so a ``https://…`` link is not partially rewritten as a path.
+    """
+    if not isinstance(value, str) or not value:
+        return value
+    out = _RAW_KEY_RE.sub("<secret>", value)
+    out = _API_KEY_RE.sub("api_key=<secret>", out)
+    out = _EMAIL_RE.sub("<email>", out)
+    out = _URL_RE.sub(_strip_url, out)
+    out = _PATH_RE.sub("<path>", out)
+    out = _INTERNAL_HOST_RE.sub("<host>", out)
+    out = _MONEY_RE.sub("<money>", out)
+    if len(out) > LONG_STRING_THRESHOLD:
+        return f"<{len(out)} chars>"
+    return out
+
+
+def scrub_value(value: Any) -> Any:
+    """Recursively scrub strings inside lists / dicts / tuples.
+
+    Booleans, numbers, and ``None`` are returned as-is. Dict keys are
+    *not* scrubbed (they are schema names, not user payloads); only
+    values pass through :func:`scrub_string`. Tuples are normalised to
+    lists because the trace lands as JSON.
+    """
+    if isinstance(value, str):
+        return scrub_string(value)
+    if isinstance(value, dict):
+        return {key: scrub_value(val) for key, val in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [scrub_value(item) for item in value]
+    return value
+
+
+__all__ = ["LONG_STRING_THRESHOLD", "scrub_string", "scrub_value"]

package/scripts/_cli/explain_last/sections/__init__.py

@@ -0,0 +1,35 @@
+"""Section renderers for the ``explain last`` Markdown projection.
+
+Each module exports a single ``render(trace) -> str`` function. The
+orchestrator at :mod:`scripts._cli.explain_last.render` calls them in
+fixed order so the Markdown output stays byte-deterministic for the
+same input ``ExplainTrace``.
+
+Splitting per CONCERN council fix — Phase 3 added ``halt`` and
+``provider`` sections without disturbing the existing ones.
+"""
+from __future__ import annotations
+
+from scripts._cli.explain_last.sections import (
+    assumptions as assumptions,
+    council as council,
+    halt as halt,
+    header as header,
+    inputs as inputs,
+    memory as memory,
+    pack as pack,
+    provider as provider,
+    route as route,
+)
+
+__all__ = [
+    "assumptions",
+    "council",
+    "halt",
+    "header",
+    "inputs",
+    "memory",
+    "pack",
+    "provider",
+    "route",
+]

package/scripts/_cli/explain_last/sections/assumptions.py

@@ -0,0 +1,21 @@
+"""Render the ``Assumptions`` section."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Assumptions", ""]
+    items = trace.get("assumptions") or []
+    if not items:
+        out.append("- (none captured)")
+        out.append("")
+        return "\n".join(out)
+    for item in items:
+        ident = item.get("id") or "(unknown)"
+        accepted = item.get("accepted", True)
+        source = item.get("source") or "unspecified"
+        marker = "[x]" if accepted else "[ ]"
+        out.append(f"- {marker} {ident}  — recorded in step `{source}`")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/council.py

@@ -0,0 +1,27 @@
+"""Render the ``Council`` section."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Council", ""]
+    members = trace.get("council") or []
+    if not members:
+        out.append("(none recorded for this run)")
+        out.append("")
+        return "\n".join(out)
+    for member in members:
+        mid = member.get("member_id") or "(unknown)"
+        verdict = member.get("verdict") or "(no verdict)"
+        out.append(f"### {mid}")
+        out.append("")
+        out.append(f"> {verdict}")
+        citations = member.get("citations") or []
+        if citations:
+            out.append("")
+            out.append("Citations:")
+            for cite in citations:
+                out.append(f"- {cite}")
+        out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/halt.py

@@ -0,0 +1,31 @@
+"""Render the ``Why halted?`` section.
+
+Surfaces ``trace.halt`` per the v1 explain-trace schema. Null halt →
+emits the *(clean run — no halt recorded)* placeholder so renders stay
+byte-deterministic even when the engine succeeded.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Why halted?", ""]
+    halt = trace.get("halt")
+    if not halt:
+        out.append("(clean run — no halt recorded)")
+        out.append("")
+        return "\n".join(out)
+    reason = halt.get("reason") or "(unknown)"
+    step = halt.get("step") or "(unspecified)"
+    out.append(f"- **Reason:** `{reason}`")
+    out.append(f"- **Hook event:** `{step}`")
+    surface = halt.get("surface") or []
+    if surface:
+        out.append("")
+        out.append("Surface emitted to the user:")
+        out.append("")
+        for line in surface:
+            out.append(f"  {line}")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/header.py

@@ -0,0 +1,24 @@
+"""Render the trace header (title + subject + started-at)."""
+from __future__ import annotations
+
+from typing import Any
+
+_SUBJECT_LABELS = {
+    "work": "/work",
+    "implement-ticket": "/implement-ticket",
+    "council": "/council",
+    "video": "/video",
+    "unknown": "(unknown)",
+}
+
+
+def render(trace: dict[str, Any]) -> str:
+    run_id = trace.get("run_id") or "(unknown)"
+    subject = trace.get("subject") or "unknown"
+    label = _SUBJECT_LABELS.get(subject, subject)
+    started = trace.get("generated_at") or ""
+    return (
+        f"# explain last — run {run_id}\n"
+        f"\n"
+        f"**Subject:** {label} · **Started:** {started}\n"
+    )

package/scripts/_cli/explain_last/sections/inputs.py

@@ -0,0 +1,27 @@
+"""Render the ``Why this profile / preset?`` knob table."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Why this profile / preset?", ""]
+    inputs = trace.get("inputs")
+    if not inputs:
+        out.append("- (none) — settings could not be resolved")
+        out.append("")
+        return "\n".join(out)
+    sources = inputs.get("source_per_knob") or {}
+    rows = [
+        ("profile.id", inputs.get("profile"), sources.get("profile")),
+        ("preset.id", inputs.get("preset"), sources.get("preset")),
+        ("cost_profile", inputs.get("cost_profile"), sources.get("cost_profile")),
+    ]
+    out.append("| knob | value | source |")
+    out.append("|---|---|---|")
+    for knob, value, source in rows:
+        value_str = "(none)" if value is None else str(value)
+        source_str = source or "default"
+        out.append(f"| {knob} | {value_str} | {source_str} |")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/memory.py

@@ -0,0 +1,21 @@
+"""Render the ``Memory hits influencing this run`` section."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Memory hits influencing this run", ""]
+    entries = trace.get("memory") or []
+    if not entries:
+        out.append("- (none)")
+        out.append("")
+        return "\n".join(out)
+    for entry in entries:
+        entry_id = entry.get("entry_id") or "(unknown)"
+        score = entry.get("hit_score")
+        used_in = entry.get("used_in") or "unspecified"
+        score_str = f"score {score:.2f}" if isinstance(score, (int, float)) else "score n/a"
+        out.append(f"- {entry_id} ({score_str}) — used in {used_in}")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/pack.py

@@ -0,0 +1,16 @@
+"""Render the ``Active pack`` section (Phase 4-discovery aware)."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    pack = trace.get("pack")
+    if not pack:
+        return ""
+    pack_id = pack.get("id") or "(unknown)"
+    reason = pack.get("reason") or ""
+    out = ["## Active pack", ""]
+    out.append(f"- {pack_id} — {reason}" if reason else f"- {pack_id}")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/provider.py

@@ -0,0 +1,26 @@
+"""Render the ``Why this provider?`` section.
+
+Only emitted when ``trace.provider`` is non-null (the v1 schema bounds
+this to ``subject == "video"`` runs where the engine wrote a provider
+selection record). All other runs render an empty string so the
+orchestrator skips the section without leaving a stray heading.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    provider = trace.get("provider")
+    if not provider:
+        return ""
+    pid = provider.get("id") or "(unknown)"
+    reason = provider.get("selection_reason") or "(no reason recorded)"
+    out = [
+        "## Why this provider?",
+        "",
+        f"- **Provider:** `{pid}`",
+        f"- **Selection reason:** {reason}",
+        "",
+    ]
+    return "\n".join(out)

package/scripts/_cli/explain_last/sections/route.py

@@ -0,0 +1,22 @@
+"""Render the ``Why this route?`` section."""
+from __future__ import annotations
+
+from typing import Any
+
+
+def render(trace: dict[str, Any]) -> str:
+    out = ["## Why this route?", ""]
+    route = trace.get("route")
+    if not route:
+        out.append("- (none) — router.json missing or unreadable")
+        out.append("")
+        return "\n".join(out)
+    matched = route.get("matched_rules") or []
+    kernel = route.get("kernel_rules") or []
+    persona = route.get("persona") or "(none)"
+    matched_str = ", ".join(matched) if matched else "(none)"
+    out.append(f"- Active rules: {matched_str}")
+    out.append(f"- Kernel rules: {len(kernel)}")
+    out.append(f"- Persona: {persona}")
+    out.append("")
+    return "\n".join(out)

package/scripts/_cli/explain_last/state_loader.py

@@ -0,0 +1,76 @@
+"""Read and validate the persisted ``.work-state.json`` envelope.
+
+The work-engine writes a versioned schema documented at
+:mod:`work_engine.state` (template) and mirrored to consumer projects.
+Phase 2 of the explain roadmap only ever reads the file. Schema-bumps
+are caught by :func:`load_state` and surface a discoverable error
+rather than rendering nonsense (backend-architect council fix —
+roadmap § "External AI-Council pass / backend-architect").
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+EXPECTED_VERSION = 1
+
+
+class StateLoadError(Exception):
+    """Raised when the state file is missing, unreadable, or version-skewed."""
+
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def load_state(state_file: Path) -> dict[str, Any]:
+    """Return the parsed state dict or raise :class:`StateLoadError`.
+
+    Validation is intentionally permissive — unknown keys pass through
+    because the schema is additive. Only three failure modes raise:
+
+    1. File does not exist.
+    2. File is not valid JSON.
+    3. ``version`` field is present and not equal to ``EXPECTED_VERSION``.
+
+    A missing ``version`` field is treated as legacy (v0) and raises
+    the same skew message; the CLI converts the raise into the
+    user-facing "trace format upgraded; rerun the upstream command on
+    this branch to regenerate" hint required by the council fix.
+    """
+    if not state_file.exists():
+        raise StateLoadError(
+            f"state file not found: {state_file}",
+            exit_code=1,
+        )
+    try:
+        text = state_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise StateLoadError(
+            f"cannot read state file {state_file}: {exc}",
+        ) from exc
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise StateLoadError(
+            f"state file {state_file} is not valid JSON: {exc}",
+        ) from exc
+    if not isinstance(payload, dict):
+        raise StateLoadError(
+            f"state file {state_file} must contain a JSON object",
+        )
+    version = payload.get("version")
+    if version != EXPECTED_VERSION:
+        raise StateLoadError(
+            (
+                "trace format upgraded; rerun the upstream command on "
+                "this branch to regenerate "
+                f"(found version={version!r}, expected {EXPECTED_VERSION})"
+            ),
+            exit_code=0,  # informational, not a failure (council fix).
+        )
+    return payload
+
+
+__all__ = ["EXPECTED_VERSION", "StateLoadError", "load_state"]