@event4u/agent-config 6.1.0 → 7.0.0

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

@@ -1,94 +0,0 @@
-"""Resolve the ``memory`` why-slot for the trace.
-
-Two sources are consulted:
-
-* ``state.memory[]`` — the work-engine writes per-run memory hits here
-  during the ``memory`` step. Each entry carries ``{entry_id,
-  hit_score, used_in}`` already shaped to the trace contract.
-* ``<root>/.agent-memory/hits.jsonl`` — optional sidecar produced by
-  the memory-MCP integration. Filtered to entries tagged with the run
-  id when present.
-
-Returns ``null`` when neither source produced a non-empty list (the
-schema accepts a null memory slot so the renderer can drop the
-section cleanly).
-"""
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-MEMORY_SIDECAR = Path(".agent-memory") / "hits.jsonl"
-
-
-def _coerce_entry(raw: dict[str, Any]) -> dict[str, Any] | None:
-    entry_id = raw.get("entry_id") or raw.get("id")
-    if not isinstance(entry_id, str) or not entry_id.strip():
-        return None
-    hit_score = raw.get("hit_score")
-    if hit_score is None:
-        hit_score = raw.get("score", 0.0)
-    try:
-        hit_score = float(hit_score)
-    except (TypeError, ValueError):
-        hit_score = 0.0
-    used_in = raw.get("used_in") or raw.get("step") or "unspecified"
-    return {
-        "entry_id": scrub_string(entry_id.strip()),
-        "hit_score": hit_score,
-        "used_in": scrub_string(str(used_in)),
-    }
-
-
-def _from_state(state: dict[str, Any]) -> list[dict[str, Any]]:
-    entries: list[dict[str, Any]] = []
-    for raw in state.get("memory", []) or []:
-        if not isinstance(raw, dict):
-            continue
-        entry = _coerce_entry(raw)
-        if entry is not None:
-            entries.append(entry)
-    return entries
-
-
-def _from_sidecar(project_root: Path, run_id: str | None) -> list[dict[str, Any]]:
-    path = project_root / MEMORY_SIDECAR
-    if not path.exists():
-        return []
-    entries: list[dict[str, Any]] = []
-    try:
-        for line in path.read_text(encoding="utf-8").splitlines():
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                raw = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            if not isinstance(raw, dict):
-                continue
-            if run_id and raw.get("run_id") not in (None, run_id):
-                continue
-            entry = _coerce_entry(raw)
-            if entry is not None:
-                entries.append(entry)
-    except OSError:
-        return []
-    return entries
-
-
-def build(
-    project_root: Path,
-    state: dict[str, Any],
-) -> list[dict[str, Any]] | None:
-    """Return the ``memory`` slot or ``None`` if no hits were captured."""
-    run_id = (state.get("input") or {}).get("data", {}).get("id")
-    entries = _from_state(state)
-    entries.extend(_from_sidecar(project_root, run_id if isinstance(run_id, str) else None))
-    return entries or None
-
-
-__all__ = ["build"]

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

@@ -1,52 +0,0 @@
-"""Builder for the ``trace.provider`` slot.
-
-Bounded to video runs (``state.directive_set == "video"``). The
-work_engine does not yet ship a video directive set — this builder is
-forward-compatible: when the engine eventually persists a provider
-selection (``state.video_provider`` or
-``state.contract.video_provider`` are both accepted shapes), the slot
-populates; otherwise it returns ``None``.
-
-The v1 schema requires ``{id, selection_reason}``. Both fields pass
-through :func:`scripts._cli.explain_last.scrubber.scrub_string` so a
-reason explaining "selected because user has $40/m budget on
-provider-x.internal" never leaks billing or hostnames.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-
-def _extract(state: dict[str, Any]) -> dict[str, Any] | None:
-    direct = state.get("video_provider")
-    if isinstance(direct, dict):
-        return direct
-    contract = state.get("contract")
-    if isinstance(contract, dict):
-        nested = contract.get("video_provider")
-        if isinstance(nested, dict):
-            return nested
-    return None
-
-
-def build(state: dict[str, Any]) -> dict[str, Any] | None:
-    if (state.get("directive_set") or "") != "video":
-        return None
-    payload = _extract(state)
-    if payload is None:
-        return None
-    pid = payload.get("id")
-    reason = payload.get("selection_reason")
-    if not isinstance(pid, str) or not pid:
-        return None
-    if not isinstance(reason, str) or not reason:
-        reason = ""
-    return {
-        "id": scrub_string(pid),
-        "selection_reason": scrub_string(reason),
-    }
-
-
-__all__ = ["build"]

package/src/scripts/_cli/explain_last/render.py

@@ -1,52 +0,0 @@
-"""Deterministic Markdown projection of an :class:`ExplainTrace`.
-
-Pure-function ``render(trace) -> str``. Same input ``ExplainTrace``
-always yields byte-identical Markdown — Phase 4 snapshot tests rely on
-this. Each section lives in its own module under :mod:`sections/`; the
-orchestrator only fixes the order. Phase 3 wired ``halt`` and
-``provider`` sections; ``halt`` always renders (clean / dirty branch
-both deterministic), ``provider`` emits an empty string on non-video
-runs so the orchestrator drops it silently.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from scripts._cli.explain_last import sections
-
-_SECTION_ORDER = (
-    sections.header,
-    sections.route,
-    sections.inputs,
-    sections.memory,
-    sections.council,
-    sections.halt,
-    sections.provider,
-    sections.assumptions,
-    sections.pack,
-)
-
-TIP_FOOTER = (
-    "_tip: pass `--json` to emit machine-readable trace; "
-    "`--quiet` to drop this footer._\n"
-)
-
-
-def render(trace: dict[str, Any], *, with_footer: bool = True) -> str:
-    """Render ``trace`` to Markdown.
-
-    ``with_footer=False`` suppresses the trailing tip line (council
-    fix: CI scripts parse the output and choke on a stray footer).
-    """
-    parts: list[str] = []
-    for section in _SECTION_ORDER:
-        chunk = section.render(trace)
-        if chunk:
-            parts.append(chunk)
-    body = "\n".join(parts).rstrip() + "\n"
-    if with_footer:
-        body += "\n" + TIP_FOOTER
-    return body
-
-
-__all__ = ["TIP_FOOTER", "render"]

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

@@ -1,59 +0,0 @@
-"""Resolve the ``route`` why-slot for the trace.
-
-Cross-references the persisted ``state.persona`` and ``state.directive_set``
-against the project's ``router.json``. Kernel rules are always-on (no
-trigger eval here); tier-1 rules are listed for the user to inspect via
-``agent-config explain route <text>`` if they want trigger reasons.
-"""
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-ROUTER_FILENAME = "router.json"
-ROUTER_RELATIVE = Path("dist") / ROUTER_FILENAME
-
-
-def _load_router(project_root: Path) -> dict[str, Any] | None:
-    path = project_root / ROUTER_RELATIVE
-    if not path.exists():
-        return None
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-
-
-def build(project_root: Path, state: dict[str, Any]) -> dict[str, Any] | None:
-    """Return the ``route`` slot or ``None`` when ``router.json`` is absent.
-
-    ``matched_rules`` is the tier-1 id list declared by the active
-    directive set (read from ``state.directive_set``). For now this is
-    the full tier-1 surface — trigger evaluation against the original
-    prompt is not persisted in v1 state and would require replaying
-    the dispatcher. ``kernel_rules`` always lists every kernel rule;
-    those are the Iron-Law floor and load unconditionally.
-    """
-    router = _load_router(project_root)
-    if router is None:
-        return None
-    kernel = [scrub_string(str(rid)) for rid in router.get("kernel", []) or []]
-    tier_1 = []
-    for entry in router.get("tier_1", []) or []:
-        if isinstance(entry, dict):
-            rid = entry.get("id")
-            if isinstance(rid, str):
-                tier_1.append(scrub_string(rid))
-    persona = state.get("persona")
-    persona_str = scrub_string(persona) if isinstance(persona, str) and persona else None
-    return {
-        "matched_rules": tier_1,
-        "kernel_rules": kernel,
-        "persona": persona_str,
-    }
-
-
-__all__ = ["build"]

package/src/scripts/_cli/explain_last/scrubber.py

@@ -1,105 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/__init__.py

@@ -1,35 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/assumptions.py

@@ -1,21 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/council.py

@@ -1,27 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/halt.py

@@ -1,31 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/header.py

@@ -1,24 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/inputs.py

@@ -1,27 +0,0 @@
-"""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")),
-        ("rule_loading_tier", inputs.get("rule_loading_tier"), sources.get("rule_loading_tier")),
-    ]
-    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/src/scripts/_cli/explain_last/sections/memory.py

@@ -1,21 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/pack.py

@@ -1,16 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/provider.py

@@ -1,26 +0,0 @@
-"""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/src/scripts/_cli/explain_last/sections/route.py

@@ -1,22 +0,0 @@
-"""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)